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>
2025-11-23 14:14:21 -08:00
parent b4e489f2de
commit bf74160f05
5 changed files with 73 additions and 12 deletions
--- 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 <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)
--- 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:<parent-id> --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:<parent-id> --json
 bd update <id> --status in_progress --json
 bd close <id> --reason "Done" --json

@@ -221,11 +221,46 @@ bd monitor --port 3000      # Custom port
 2. **Claim your task**: `bd update <id> --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 <new-id> <current-id> --type discovered-from`
-   - New way (one command): `bd create "Found bug in auth" -t bug -p 1 --deps discovered-from:<current-id> --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 <new-id> <current-id> --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:<current-id> --json`
 5. **Complete**: `bd close <id> --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 <id> --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:<parent-id>`
+   - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
 5. **Complete**: `bd close <id> --reason "Done"`

 ### Auto-Sync
--- 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
--- 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.
    """
--- 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{