From bf74160f055352fbf8314915a4cd65318f4f0d16 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sun, 23 Nov 2025 14:14:21 -0800 Subject: [PATCH] Fix GH#366: Encourage descriptions when creating issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .github/copilot-instructions.md | 8 ++- AGENTS.md | 55 ++++++++++++++++--- cmd/bd/create.go | 8 +++ integrations/beads-mcp/src/beads_mcp/tools.py | 7 +++ internal/rpc/server_issues_epics.go | 7 +++ 5 files changed, 73 insertions(+), 12 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0c6b3c7a..1065afa4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -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 --status in_progress --json bd close --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 --status in_progress` 3. **Work on it**: Implement, test, document -4. **Discover new work?** `bd create "Found bug" -p 1 --deps discovered-from: --json` +4. **Discover new work?** `bd create "Found bug" --description="What was found and why" -p 1 --deps discovered-from: --json` 5. **Complete**: `bd close --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) diff --git a/AGENTS.md b/AGENTS.md index fe43ee29..9b458318 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -173,8 +173,8 @@ bd ready --json # Unblocked issues bd stale --days 30 --json # Forgotten issues # Create and manage issues -bd create "Issue title" -t bug|feature|task -p 0-4 --json -bd create "Found bug" -p 1 --deps discovered-from: --json +bd create "Issue title" --description="Detailed context about the issue" -t bug|feature|task -p 0-4 --json +bd create "Found bug" --description="What the bug is and how it was discovered" -p 1 --deps discovered-from: --json bd update --status in_progress --json bd close --reason "Done" --json @@ -221,11 +221,46 @@ bd monitor --port 3000 # Custom port 2. **Claim your task**: `bd update --status in_progress` 3. **Work on it**: Implement, test, document 4. **Discover new work**: If you find bugs or TODOs, create issues: - - Old way (two commands): `bd create "Found bug in auth" -t bug -p 1 --json` then `bd dep add --type discovered-from` - - New way (one command): `bd create "Found bug in auth" -t bug -p 1 --deps discovered-from: --json` + - Old way (two commands): `bd create "Found bug in auth" --description="Details about the bug" -t bug -p 1 --json` then `bd dep add --type discovered-from` + - New way (one command): `bd create "Found bug in auth" --description="Login fails with 500 when password has special chars" -t bug -p 1 --deps discovered-from: --json` 5. **Complete**: `bd close --reason "Implemented"` 6. **Sync at end of session**: `bd sync` (see "Agent Session Workflow" below) +### IMPORTANT: Always Include Issue Descriptions + +**Issues without descriptions lack context for future work.** When creating issues, always include a meaningful description with: + +- **Why** the issue exists (problem statement or need) +- **What** needs to be done (scope and approach) +- **How** you discovered it (if applicable during work) + +**Good examples:** + +```bash +# Bug discovered during work +bd create "Fix auth bug in login handler" \ + --description="Login fails with 500 error when password contains special characters like quotes. Found while testing GH#123 feature. Stack trace shows unescaped SQL in auth/login.go:45." \ + -t bug -p 1 --deps discovered-from:bd-abc --json + +# Feature request +bd create "Add password reset flow" \ + --description="Users need ability to reset forgotten passwords via email. Should follow OAuth best practices and include rate limiting to prevent abuse." \ + -t feature -p 2 --json + +# Technical debt +bd create "Refactor auth package for testability" \ + --description="Current auth code has tight DB coupling making unit tests difficult. Need to extract interfaces and add dependency injection. Blocks writing tests for bd-xyz." \ + -t task -p 3 --json +``` + +**Bad examples (missing context):** + +```bash +bd create "Fix auth bug" -t bug -p 1 --json # What bug? Where? Why? +bd create "Add feature" -t feature --json # What feature? Why needed? +bd create "Refactor code" -t task --json # What code? Why refactor? +``` + ### Optional: Agent Mail for Multi-Agent Coordination **⚠️ NOT CURRENTLY CONFIGURED** - The mcp-agent-mail server is not set up for this project. Do not attempt to use mcp-agent-mail tools. @@ -339,7 +374,7 @@ bd import -i issues.jsonl --dedupe-after 3. **During work discovery**: Check for duplicates when filing discovered-from issues ```bash - # Before: bd create "Fix auth bug" --deps discovered-from:bd-100 + # Before: bd create "Fix auth bug" --description="Details..." --deps discovered-from:bd-100 # First: bd list --json | grep -i "auth bug" # Then decide: create new or link to existing ``` @@ -382,7 +417,9 @@ bd show bd-41 --json # Verify merged content - Add labels like `duplicate` to source issues before merging (for tracking) - File a discovered-from issue if you found duplicates during work: ```bash - bd create "Found duplicates during bd-X" -p 2 --deps discovered-from:bd-X --json + bd create "Found duplicates during bd-X" \ + --description="Issues bd-A, bd-B, and bd-C are duplicates and need merging" \ + -p 2 --deps discovered-from:bd-X --json ``` ## Development Guidelines @@ -508,8 +545,8 @@ bd ready --json **Create new issues:** ```bash -bd create "Issue title" -t bug|feature|task -p 0-4 --json -bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json +bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json +bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json ``` **Claim and update:** @@ -547,7 +584,7 @@ bd close bd-42 --reason "Completed" --json 2. **Claim your task**: `bd update --status in_progress` 3. **Work on it**: Implement, test, document 4. **Discover new work?** Create linked issue: - - `bd create "Found bug" -p 1 --deps discovered-from:` + - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:` 5. **Complete**: `bd close --reason "Done"` ### Auto-Sync diff --git a/cmd/bd/create.go b/cmd/bd/create.go index 39eaf308..d5c96ead 100644 --- a/cmd/bd/create.go +++ b/cmd/bd/create.go @@ -82,6 +82,14 @@ var createCmd = &cobra.Command{ description = tmpl.Description } + // Warn if creating an issue without a description (unless it's a test issue) + if description == "" && !strings.Contains(strings.ToLower(title), "test") { + yellow := color.New(color.FgYellow).SprintFunc() + fmt.Fprintf(os.Stderr, "%s Creating issue without description.\n", yellow("⚠")) + fmt.Fprintf(os.Stderr, " Issues without descriptions lack context for future work.\n") + fmt.Fprintf(os.Stderr, " Consider adding --description=\"Why this issue exists and what needs to be done\"\n") + } + design, _ := cmd.Flags().GetString("design") if design == "" && tmpl != nil { design = tmpl.Design diff --git a/integrations/beads-mcp/src/beads_mcp/tools.py b/integrations/beads-mcp/src/beads_mcp/tools.py index 4e6e84e9..c33b2917 100644 --- a/integrations/beads-mcp/src/beads_mcp/tools.py +++ b/integrations/beads-mcp/src/beads_mcp/tools.py @@ -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. """ diff --git a/internal/rpc/server_issues_epics.go b/internal/rpc/server_issues_epics.go index 1add520f..c80b94f5 100644 --- a/internal/rpc/server_issues_epics.go +++ b/internal/rpc/server_issues_epics.go @@ -3,6 +3,7 @@ package rpc import ( "encoding/json" "fmt" + "os" "strings" "time" @@ -89,6 +90,12 @@ func (s *Server) handleCreate(req *Request) Response { } } + // Warn if creating an issue without a description (unless it's a test issue) + if createArgs.Description == "" && !strings.Contains(strings.ToLower(createArgs.Title), "test") { + // Log warning to daemon logs (stderr goes to daemon logs) + fmt.Fprintf(os.Stderr, "[WARNING] Creating issue '%s' without description. Issues without descriptions lack context for future work.\n", createArgs.Title) + } + store := s.storage if store == nil { return Response{