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

@@ -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{