Fix GH#366: Encourage descriptions when creating issues

Addresses GitHub Discussion #366 where users reported Claude Code
creating issues with titles but no descriptions.

Two-pronged solution:

1. Documentation improvements (bd-na8r):
   - Updated AGENTS.md with prominent guidance section
   - Added good/bad examples showing why/what/how to include
   - Updated all bd create examples to include --description
   - Enhanced MCP tool docstring with importance note
   - Updated .github/copilot-instructions.md

2. Code validation (bd-bcrt):
   - Added friendly yellow warning when description is empty
   - Warning skips test issues (title contains "test")
   - Works in both CLI and daemon modes
   - Non-blocking to preserve quick workflows

Evidence from our own projects showed significant empty description
rates:
- ~/src/beads: 110/630 (17.5%)
- ~/wyvern: 8/119 (6.7%)
- ~/src/vc: 3/170 (1.8%)

Fixes bd-0tr0, bd-na8r, bd-bcrt

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-11-23 14:14:21 -08:00
parent b4e489f2de
commit bf74160f05
5 changed files with 73 additions and 12 deletions

View File

@@ -362,6 +362,13 @@ async def beads_create_issue(
) -> Issue:
"""Create a new issue.
IMPORTANT: Always provide a meaningful description with context about:
- Why this issue exists (problem statement or need)
- What needs to be done (scope and approach)
- How you discovered it (if applicable)
Issues without descriptions lack context for future work and make prioritization difficult.
Use this when you discover new work during your session.
Link it back with beads_add_dependency using 'discovered-from' type.
"""