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

@@ -50,8 +50,8 @@
bd ready --json # Unblocked issues
bd stale --days 30 --json # Forgotten issues
# Create and manage
bd create "Title" -t bug|feature|task -p 0-4 --json
# Create and manage (ALWAYS include --description)
bd create "Title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd update <id> --status in_progress --json
bd close <id> --reason "Done" --json
@@ -68,10 +68,12 @@ bd sync # Force immediate export/commit/push
1. **Check ready work**: `bd ready --json`
2. **Claim task**: `bd update <id> --status in_progress`
3. **Work on it**: Implement, test, document
4. **Discover new work?** `bd create "Found bug" -p 1 --deps discovered-from:<parent-id> --json`
4. **Discover new work?** `bd create "Found bug" --description="What was found and why" -p 1 --deps discovered-from:<parent-id> --json`
5. **Complete**: `bd close <id> --reason "Done" --json`
6. **Sync**: `bd sync` (flushes changes to git immediately)
**IMPORTANT**: Always include `--description` when creating issues. Issues without descriptions lack context for future work.
### Priorities
- `0` - Critical (security, data loss, broken builds)