Add issue triage system to prevent deferred issue pile-up
- /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 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
14
README.md
14
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 |
|
||||
|
||||
---
|
||||
|
||||
202
commands/gsd/consider-issues.md
Normal file
202
commands/gsd/consider-issues.md
Normal file
@@ -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
|
||||
---
|
||||
|
||||
<objective>
|
||||
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.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
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"`
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="verify">
|
||||
**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.
|
||||
</step>
|
||||
|
||||
<step name="parse">
|
||||
**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.
|
||||
</step>
|
||||
|
||||
<step name="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
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
**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]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer_actions">
|
||||
**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
|
||||
</step>
|
||||
|
||||
<step name="execute_actions">
|
||||
**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
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] 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
|
||||
</success_criteria>
|
||||
@@ -10,6 +10,7 @@ allowed-tools:
|
||||
- Grep
|
||||
- Task
|
||||
- AskUserQuestion
|
||||
- SlashCommand
|
||||
---
|
||||
|
||||
<objective>
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -1157,6 +1157,45 @@ EOF
|
||||
For commit message conventions and git workflow patterns, see ~/.claude/get-shit-done/references/git-integration.md
|
||||
</step>
|
||||
|
||||
<step name="check_phase_issues">
|
||||
**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
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
**Check workflow config for gate behavior:**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user