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:
8
.github/copilot-instructions.md
vendored
8
.github/copilot-instructions.md
vendored
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user