From 2e1b0b8d70269f0c7ce96ca3667978327bcad810 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Mon, 15 Dec 2025 08:25:51 -0600 Subject: [PATCH] Add issue triage system to prevent deferred issue pile-up MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - /gsd:consider-issues reviews issues with codebase context - Phase completion now prompts for issue review - Auto-categorizes: resolved, urgent, natural-fit, can-wait - README: explain context exhaustion problem and subagent solution 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 14 +- commands/gsd/consider-issues.md | 202 +++++++++++++++++++++++ commands/gsd/execute-plan.md | 1 + commands/gsd/help.md | 14 ++ get-shit-done/workflows/execute-phase.md | 39 +++++ 5 files changed, 266 insertions(+), 4 deletions(-) create mode 100644 commands/gsd/consider-issues.md diff --git a/README.md b/README.md index abe2558b7..36c717ab2 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,7 @@ GSD handles it for you: | `STATE.md` | Decisions, blockers, position — memory across sessions | | `PLAN.md` | Atomic task with XML structure, verification steps | | `SUMMARY.md` | What happened, what changed, committed to history | +| `ISSUES.md` | Deferred enhancements tracked across sessions | Size limits based on where Claude's quality degrades. Stay under, get consistent excellence. @@ -109,11 +110,15 @@ Precise instructions. No guessing. Verification built in. ### Subagent Execution -Plans run in fresh contexts: +As Claude fills its context window, quality degrades. You've seen it: "Due to context limits, I'll be more concise now." That "concision" is code for cutting corners. -- 0% overhead to start -- Maximum quality, zero degradation -- Walk away, come back to completed work +GSD prevents this. Each plan is maximum 3 tasks. Each plan runs in a fresh subagent — 200k tokens purely for implementation, zero accumulated garbage. + +- Task 1: fresh context, full quality +- Task 2: fresh context, full quality +- Task 3: fresh context, full quality + +No degradation. Walk away, come back to completed work. ### Clean Git History @@ -147,6 +152,7 @@ You're never locked in. The system adapts. | `/gsd:list-phase-assumptions [N]` | See what Claude thinks before you correct it | | `/gsd:pause-work` | Create handoff file when stopping mid-phase | | `/gsd:resume-work` | Restore from last session | +| `/gsd:consider-issues` | Review deferred issues, close resolved, identify urgent | | `/gsd:help` | Show all commands and usage guide | --- diff --git a/commands/gsd/consider-issues.md b/commands/gsd/consider-issues.md new file mode 100644 index 000000000..b60dbff63 --- /dev/null +++ b/commands/gsd/consider-issues.md @@ -0,0 +1,202 @@ +--- +description: Review deferred issues with codebase context, close resolved ones, identify urgent ones +allowed-tools: + - Read + - Bash + - Grep + - Glob + - Edit + - AskUserQuestion + - SlashCommand +--- + + +Review all open issues from ISSUES.md with current codebase context. Identify which issues are resolved (can close), which are now urgent (should address), and which can continue waiting. + +This prevents issue pile-up by providing a triage mechanism with codebase awareness. + + + +Issues file: !`cat .planning/ISSUES.md 2>/dev/null || echo "NO_ISSUES_FILE"` +Project state: !`cat .planning/STATE.md 2>/dev/null | head -50` +Current phase: !`grep -E "^Phase:" .planning/STATE.md 2>/dev/null || echo "UNKNOWN"` +Roadmap phases: !`grep -E "^### Phase [0-9]" .planning/ROADMAP.md 2>/dev/null || echo "NO_ROADMAP"` + + + + + +**Verify issues file exists:** + +If no `.planning/ISSUES.md`: +``` +No issues file found. + +This means no enhancements have been deferred yet (Rule 5 hasn't triggered). + +Nothing to review. +``` +Exit. + +If ISSUES.md exists but has no open issues (only template or empty "Open Enhancements"): +``` +No open issues to review. + +All clear - continue with current work. +``` +Exit. + + + +**Parse all open issues:** + +Extract from "## Open Enhancements" section: +- ISS number (ISS-001, ISS-002, etc.) +- Brief description +- Discovered phase/date +- Type (Performance/Refactoring/UX/Testing/Documentation/Accessibility) +- Description details +- Effort estimate + +Build list of issues to analyze. + + + +**For each open issue, perform codebase analysis:** + +1. **Check if still relevant:** + - Search codebase for related code/files mentioned in issue + - If code no longer exists or was significantly refactored: likely resolved + +2. **Check if accidentally resolved:** + - Look for commits/changes that may have addressed this + - Check if the enhancement was implemented as part of other work + +3. **Assess current urgency:** + - Is this blocking upcoming phases? + - Has this become a pain point mentioned in recent summaries? + - Is this now affecting code we're actively working on? + +4. **Check natural fit:** + - Does this align with an upcoming phase in the roadmap? + - Would addressing it now touch the same files as current work? + +**Categorize each issue:** +- **Resolved** - Can be closed (code changed, no longer applicable) +- **Urgent** - Should address before continuing (blocking or causing problems) +- **Natural fit** - Good candidate for upcoming phase X +- **Can wait** - Keep deferred, no change in status + + + +**Present categorized report:** + +``` +# Issue Review + +**Analyzed:** [N] open issues +**Last reviewed:** [today's date] + +## Resolved (can close) + +### ISS-XXX: [description] +**Reason:** [Why it's resolved - code changed, implemented elsewhere, no longer applicable] +**Evidence:** [What you found - file changes, missing code, etc.] + +[Repeat for each resolved issue, or "None" if none resolved] + +--- + +## Urgent (should address now) + +### ISS-XXX: [description] +**Why urgent:** [What changed - blocking next phase, causing active problems, etc.] +**Recommendation:** Insert plan before Phase [X] / Add to current phase +**Effort:** [Quick/Medium/Substantial] + +[Repeat for each urgent issue, or "None - all issues can wait" if none urgent] + +--- + +## Natural Fit for Upcoming Work + +### ISS-XXX: [description] +**Fits with:** Phase [X] - [phase name] +**Reason:** [Same files, same subsystem, natural inclusion] + +[Repeat for each, or "None" if no natural fits] + +--- + +## Can Wait (no change) + +### ISS-XXX: [description] +**Status:** Still valid, not urgent, keep deferred + +[Repeat for each, or list ISS numbers if many] +``` + + + +**Offer batch actions:** + +Based on analysis, present options: + +``` +## Actions + +What would you like to do? +``` + +Use AskUserQuestion with appropriate options based on findings: + +**If resolved issues exist:** +- "Close resolved issues" - Move to Closed Enhancements section +- "Review each first" - Show details before closing + +**If urgent issues exist:** +- "Insert urgent phase" - Create phase to address urgent issues (/gsd:insert-phase) +- "Add to current plan" - Include in next plan being created +- "Defer anyway" - Keep as-is despite urgency + +**If natural fits exist:** +- "Note for phase planning" - Will be picked up during /gsd:plan-phase +- "Add explicit reminder" - Update issue with "Include in Phase X" + +**Always include:** +- "Done for now" - Exit without changes + + + +**Execute selected actions:** + +**If closing resolved issues:** +1. Read current ISSUES.md +2. For each resolved issue: + - Remove from "## Open Enhancements" + - Add to "## Closed Enhancements" with resolution note: + ``` + ### ISS-XXX: [description] + **Resolved:** [date] - [reason] + ``` +3. Write updated ISSUES.md +4. Update STATE.md deferred issues count + +**If inserting urgent phase:** +- Invoke: `SlashCommand("/gsd:insert-phase [after-phase] Address urgent issues ISS-XXX, ISS-YYY")` + +**If noting for phase planning:** +- Update issue's "Suggested phase" field with specific phase number +- These will be picked up by /gsd:plan-phase workflow + + + + + +- [ ] All open issues analyzed against current codebase +- [ ] Each issue categorized (resolved/urgent/natural-fit/can-wait) +- [ ] Clear reasoning provided for each categorization +- [ ] Actions offered based on findings +- [ ] ISSUES.md updated if user takes action +- [ ] STATE.md updated if issue count changes + diff --git a/commands/gsd/execute-plan.md b/commands/gsd/execute-plan.md index b62fbd2f6..f43aaac92 100644 --- a/commands/gsd/execute-plan.md +++ b/commands/gsd/execute-plan.md @@ -10,6 +10,7 @@ allowed-tools: - Grep - Task - AskUserQuestion + - SlashCommand --- diff --git a/commands/gsd/help.md b/commands/gsd/help.md index 083136350..cb3f94051 100644 --- a/commands/gsd/help.md +++ b/commands/gsd/help.md @@ -172,6 +172,19 @@ Create context handoff when pausing work mid-phase. Usage: `/gsd:pause-work` +### Issue Management + +**`/gsd:consider-issues`** +Review deferred issues with codebase context. + +- Analyzes all open issues against current codebase state +- Identifies resolved issues (can close) +- Identifies urgent issues (should address now) +- Identifies natural fits for upcoming phases +- Offers batch actions (close, insert phase, note for planning) + +Usage: `/gsd:consider-issues` + ### Utility Commands **`/gsd:help`** @@ -184,6 +197,7 @@ Show this command reference. ├── PROJECT.md # Project vision ├── ROADMAP.md # Current phase breakdown ├── STATE.md # Project memory & context +├── ISSUES.md # Deferred enhancements (created when needed) ├── config.json # Workflow mode & gates └── phases/ ├── 01-foundation/ diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md index 6f0f15e67..089a5dbda 100644 --- a/get-shit-done/workflows/execute-phase.md +++ b/get-shit-done/workflows/execute-phase.md @@ -1157,6 +1157,45 @@ EOF For commit message conventions and git workflow patterns, see ~/.claude/get-shit-done/references/git-integration.md + +**Check if issues were created during this phase:** + +```bash +# Check if ISSUES.md exists and has issues from current phase +if [ -f .planning/ISSUES.md ]; then + grep -E "Phase ${PHASE}.*Task" .planning/ISSUES.md | grep -v "^#" || echo "NO_ISSUES_THIS_PHASE" +fi +``` + +**If issues were created during this phase:** + +``` +📋 Issues logged during this phase: +- ISS-XXX: [brief description] +- ISS-YYY: [brief description] + +Review these now? +``` + +Use AskUserQuestion: +- header: "Phase Issues" +- question: "[N] issues were logged during this phase. Review now?" +- options: + - "Review issues" - Analyze with /gsd:consider-issues + - "Continue" - Address later, proceed to next work + +**If "Review issues" selected:** +- Invoke: `SlashCommand("/gsd:consider-issues")` +- After consider-issues completes, return to offer_next + +**If "Continue" selected or no issues found:** +- Proceed to offer_next step + +**In YOLO mode:** +- Note issues were logged but don't prompt: `📋 [N] issues logged this phase (review later with /gsd:consider-issues)` +- Continue to offer_next automatically + + **Check workflow config for gate behavior:**