chore: remove dead ISSUES.md system
Remove the global ISSUES.md deferred enhancement tracking system. - Delete /gsd:consider-issues command (never used) - Delete issues.md template (never instantiated) - Remove Rule 5 from deviation rules (never triggered) - Remove all ISSUES.md, ISS-XXX, and "deferred issues" references - Update STATE.md to track pending todos instead The ISSUES.md system was designed to capture non-critical enhancements during plan execution via "Rule 5", but it never fired in practice across 100+ projects. The system added ~350 lines of dead code. The /gsd:add-todo and /gsd:check-todos system serves the same purpose and is actually used. Note: UAT *-ISSUES.md files (per-plan, created by /gsd:verify-work) are unaffected - those are a separate, active system. Closes #56 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -34,7 +34,6 @@ cat .planning/STATE.md 2>/dev/null
|
||||
|
||||
- Current position (phase, plan, status)
|
||||
- Accumulated decisions (constraints on this execution)
|
||||
- Deferred issues (context for deviations)
|
||||
- Blockers/concerns (things to watch for)
|
||||
|
||||
**If file missing but .planning/ exists:**
|
||||
|
||||
@@ -437,7 +437,6 @@ Extract completed milestone details and create archive file.
|
||||
- {{PHASES_SECTION}} — Full phase details extracted
|
||||
- {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
|
||||
- {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
|
||||
- {{ISSUES_DEFERRED_TO_LATER}} — From ISSUES.md
|
||||
|
||||
6. Write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ Extract:
|
||||
|
||||
- Previous milestone version (e.g., v1.0)
|
||||
- Last phase number used
|
||||
- Deferred issues from STATE.md
|
||||
- Pending todos from STATE.md
|
||||
- Project context from PROJECT.md (What This Is, Core Value)
|
||||
|
||||
**Check for milestone context from discuss-milestone:**
|
||||
|
||||
@@ -130,7 +130,7 @@ Use decimal phases (2.1, 2.2) for urgent insertions:
|
||||
- Urgent work that can't wait for next milestone
|
||||
- Critical bugs blocking progress
|
||||
- Security patches needing immediate attention
|
||||
- NOT for scope creep or "nice to haves" (those go in ISSUES.md)
|
||||
- NOT for scope creep or "nice to haves" (capture with /gsd:add-todo instead)
|
||||
|
||||
**Phase execution order:**
|
||||
Numeric sort: 1 → 1.1 → 1.2 → 2 → 2.1 → 3
|
||||
@@ -368,7 +368,7 @@ Recent decisions affecting current work:
|
||||
|
||||
(None yet)
|
||||
|
||||
### Deferred Issues
|
||||
### Pending Todos
|
||||
|
||||
None yet.
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ The primary question is: **What do you want to build/add/fix?**
|
||||
Everything else (scope, priority, constraints) is secondary and derived from features.
|
||||
|
||||
Check for inputs:
|
||||
- Deferred issues from STATE.md (potential features)
|
||||
- Pending todos from STATE.md (potential features)
|
||||
- Known gaps or pain points from usage
|
||||
- User's ideas for what's next
|
||||
|
||||
@@ -65,7 +65,7 @@ Check for inputs:
|
||||
Use AskUserQuestion:
|
||||
- header: "Next"
|
||||
- question: "What do you want to add, improve, or fix in this milestone?"
|
||||
- options: [Deferred issues from STATE.md if any] + ["New features", "Improvements to existing", "Bug fixes", "Let me describe"]
|
||||
- options: [Pending todos from STATE.md if any] + ["New features", "Improvements to existing", "Bug fixes", "Let me describe"]
|
||||
|
||||
**2. Explore features:**
|
||||
|
||||
@@ -84,7 +84,7 @@ If they described a general direction:
|
||||
If they're not sure:
|
||||
- header: "Starting Points"
|
||||
- question: "What's been frustrating or missing?"
|
||||
- options: [Deferred issues from STATE.md + pain point categories + "Let me think about it"]
|
||||
- options: [Pending todos from STATE.md + pain point categories + "Let me think about it"]
|
||||
|
||||
**3. Prioritize:**
|
||||
|
||||
|
||||
@@ -22,7 +22,6 @@ cat .planning/STATE.md 2>/dev/null
|
||||
**If file exists:** Parse and internalize:
|
||||
- Current position (phase, plan, status)
|
||||
- Accumulated decisions (constraints on this execution)
|
||||
- Deferred issues (context for deviations)
|
||||
- Blockers/concerns (things to watch for)
|
||||
|
||||
**If file missing but .planning/ exists:**
|
||||
|
||||
@@ -19,7 +19,6 @@ cat .planning/STATE.md 2>/dev/null
|
||||
|
||||
- Current position (phase, plan, status)
|
||||
- Accumulated decisions (constraints on this execution)
|
||||
- Deferred issues (context for deviations)
|
||||
- Blockers/concerns (things to watch for)
|
||||
- Brief alignment status
|
||||
|
||||
@@ -804,60 +803,28 @@ Proceed with proposed change? (yes / different approach / defer)
|
||||
3. WAIT for user response
|
||||
4. If approved: implement, track as `[Rule 4 - Architectural] [description]`
|
||||
5. If different approach: discuss and implement
|
||||
6. If deferred: log to ISSUES.md, continue without change
|
||||
6. If deferred: note in Summary and continue without change
|
||||
|
||||
**User decision required.** These changes affect system design.
|
||||
|
||||
---
|
||||
|
||||
**RULE 5: Log non-critical enhancements**
|
||||
|
||||
**Trigger:** Improvement that would enhance code but isn't essential now
|
||||
|
||||
**Action:** Add to .planning/ISSUES.md automatically, continue task
|
||||
|
||||
**Examples:**
|
||||
|
||||
- Performance optimization (works correctly, just slower than ideal)
|
||||
- Code refactoring (works, but could be cleaner/DRY-er)
|
||||
- Better naming (works, but variables could be clearer)
|
||||
- Organizational improvements (works, but file structure could be better)
|
||||
- Nice-to-have UX improvements (works, but could be smoother)
|
||||
- Additional test coverage beyond basics (basics exist, could be more thorough)
|
||||
- Documentation improvements (code works, docs could be better)
|
||||
- Accessibility enhancements beyond minimum
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Create .planning/ISSUES.md if doesn't exist (use `~/.claude/get-shit-done/templates/issues.md`)
|
||||
2. Add entry with ISS-XXX number (auto-increment)
|
||||
3. Brief notification: `📋 Logged enhancement: [brief] (ISS-XXX)`
|
||||
4. Continue task without implementing
|
||||
|
||||
**No user permission needed.** Logging for future consideration.
|
||||
|
||||
---
|
||||
|
||||
**RULE PRIORITY (when multiple could apply):**
|
||||
|
||||
1. **If Rule 4 applies** → STOP and ask (architectural decision)
|
||||
2. **If Rules 1-3 apply** → Fix automatically, track for Summary
|
||||
3. **If Rule 5 applies** → Log to ISSUES.md, continue
|
||||
4. **If genuinely unsure which rule** → Apply Rule 4 (ask user)
|
||||
3. **If genuinely unsure which rule** → Apply Rule 4 (ask user)
|
||||
|
||||
**Edge case guidance:**
|
||||
|
||||
- "This validation is missing" → Rule 2 (critical for security)
|
||||
- "This validation could be better" → Rule 5 (enhancement)
|
||||
- "This crashes on null" → Rule 1 (bug)
|
||||
- "This could be faster" → Rule 5 (enhancement) UNLESS actually timing out → Rule 2 (critical)
|
||||
- "Need to add table" → Rule 4 (architectural)
|
||||
- "Need to add column" → Rule 1 or 2 (depends: fixing bug or adding critical field)
|
||||
|
||||
**When in doubt:** Ask yourself "Does this affect correctness, security, or ability to complete task?"
|
||||
|
||||
- YES → Rules 1-3 (fix automatically)
|
||||
- NO → Rule 5 (log it)
|
||||
- MAYBE → Rule 4 (ask user)
|
||||
|
||||
</deviation_rules>
|
||||
@@ -901,16 +868,9 @@ None - plan executed exactly as written.
|
||||
- **Verification:** Expired token test passes - properly rejects with 401
|
||||
- **Commit:** def456g
|
||||
|
||||
### Deferred Enhancements
|
||||
|
||||
Logged to .planning/ISSUES.md for future consideration:
|
||||
|
||||
- ISS-001: Refactor UserService into smaller modules (discovered in Task 3)
|
||||
- ISS-002: Add connection pooling for Redis (discovered in Task 6)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 4 auto-fixed (1 bug, 1 missing critical, 1 blocking, 1 architectural with approval), 3 deferred
|
||||
**Total deviations:** 4 auto-fixed (1 bug, 1 missing critical, 1 blocking, 1 architectural with approval)
|
||||
**Impact on plan:** All auto-fixes necessary for correctness/security/performance. No scope creep.
|
||||
```
|
||||
|
||||
@@ -1307,10 +1267,7 @@ Before writing summary content, populate frontmatter fields from execution conte
|
||||
5. **Decisions:**
|
||||
- key-decisions: Extract from "Decisions Made" section
|
||||
|
||||
6. **Issues:**
|
||||
- issues-created: Check if ISSUES.md was updated during execution
|
||||
|
||||
7. **Metrics:**
|
||||
6. **Metrics:**
|
||||
- duration: From $DURATION variable
|
||||
- completed: From $PLAN_END_TIME (date only, format YYYY-MM-DD)
|
||||
|
||||
@@ -1405,12 +1362,6 @@ Extract decisions, issues, and concerns from SUMMARY.md into STATE.md accumulate
|
||||
- Add each decision to STATE.md Decisions table
|
||||
- Format: `| [phase number] | [decision summary] | [rationale] |`
|
||||
|
||||
**Deferred Issues:**
|
||||
|
||||
- Read SUMMARY.md to check if new issues were logged to ISSUES.md
|
||||
- If new ISS-XXX entries created:
|
||||
- Update STATE.md "Deferred Issues" section
|
||||
|
||||
**Blockers/Concerns:**
|
||||
|
||||
- Read SUMMARY.md "## Next Phase Readiness" section
|
||||
@@ -1585,45 +1536,6 @@ git commit --amend --no-edit # Include in metadata commit
|
||||
Skip this step.
|
||||
</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">
|
||||
**MANDATORY: Verify remaining work before presenting next steps.**
|
||||
|
||||
|
||||
@@ -55,7 +55,7 @@ PLAN.md IS the prompt that Claude executes. Plans are grouped into execution wav
|
||||
Read `.planning/STATE.md` and parse:
|
||||
- Current position (which phase we're planning)
|
||||
- Accumulated decisions (constraints on this phase)
|
||||
- Deferred issues (candidates for inclusion)
|
||||
- Pending todos (candidates for inclusion)
|
||||
- Blockers/concerns (things this phase may address)
|
||||
- Brief alignment status
|
||||
|
||||
@@ -186,19 +186,19 @@ Only now open and read complete SUMMARY.md files for the selected relevant phase
|
||||
- "Issues Encountered" that might affect current phase
|
||||
- "Deviations from Plan" for patterns
|
||||
|
||||
**From STATE.md:** Decisions → constrain approach. Deferred issues → candidates. Blockers → may need to address.
|
||||
**From STATE.md:** Decisions → constrain approach. Pending todos → candidates. Blockers → may need to address.
|
||||
|
||||
**From ISSUES.md:**
|
||||
**From pending todos:**
|
||||
|
||||
```bash
|
||||
cat .planning/ISSUES.md 2>/dev/null
|
||||
ls .planning/todos/pending/*.md 2>/dev/null
|
||||
```
|
||||
|
||||
Assess each open issue - relevant to this phase? Waiting long enough? Natural to address now? Blocking something?
|
||||
Assess each pending todo - relevant to this phase? Natural to address now?
|
||||
|
||||
**Answer before proceeding:**
|
||||
- Q1: What decisions from previous phases constrain this phase?
|
||||
- Q2: Are there deferred issues that should become tasks?
|
||||
- Q2: Are there pending todos that should become tasks?
|
||||
- Q3: Are there concerns from "Next Phase Readiness" that apply?
|
||||
- Q4: Given all context, does the roadmap's description still make sense?
|
||||
|
||||
@@ -208,7 +208,7 @@ Assess each open issue - relevant to this phase? Waiting long enough? Natural to
|
||||
- Established patterns (from frontmatter)
|
||||
- Key files to reference (from frontmatter)
|
||||
- Applicable decisions (from frontmatter + full summary)
|
||||
- Issues being addressed (from ISSUES.md)
|
||||
- Todos being addressed (from pending todos)
|
||||
- Concerns being verified (from "Next Phase Readiness")
|
||||
</step>
|
||||
|
||||
|
||||
@@ -44,7 +44,7 @@ cat .planning/PROJECT.md
|
||||
- **Current Position**: Phase X of Y, Plan A of B, Status
|
||||
- **Progress**: Visual progress bar
|
||||
- **Recent Decisions**: Key decisions affecting current work
|
||||
- **Deferred Issues**: Open items awaiting attention
|
||||
- **Pending Todos**: Ideas captured during sessions
|
||||
- **Blockers/Concerns**: Issues carried forward
|
||||
- **Session Continuity**: Where we left off, any resume files
|
||||
|
||||
@@ -123,8 +123,8 @@ Present complete project status to user:
|
||||
|
||||
Resume with: /gsd:resume-task
|
||||
|
||||
[If deferred issues exist:]
|
||||
📋 [N] deferred issues awaiting attention
|
||||
[If pending todos exist:]
|
||||
📋 [N] pending todos — /gsd:check-todos to review
|
||||
|
||||
[If blockers exist:]
|
||||
⚠️ Carried concerns:
|
||||
@@ -190,7 +190,7 @@ What would you like to do?
|
||||
|
||||
[Secondary options:]
|
||||
2. Review current phase status
|
||||
3. Check deferred issues ([N] open)
|
||||
3. Check pending todos ([N] pending)
|
||||
4. Review brief alignment
|
||||
5. Something else
|
||||
```
|
||||
@@ -244,7 +244,7 @@ Based on user selection, route to appropriate workflow:
|
||||
---
|
||||
```
|
||||
- **Transition** → ./transition.md
|
||||
- **Review issues** → Read ISSUES.md, present summary
|
||||
- **Check todos** → Read .planning/todos/pending/, present summary
|
||||
- **Review alignment** → Read PROJECT.md, compare to current state
|
||||
- **Something else** → Ask what they need
|
||||
</step>
|
||||
@@ -274,8 +274,8 @@ If STATE.md is missing but other artifacts exist:
|
||||
|
||||
1. Read PROJECT.md → Extract "What This Is" and Core Value
|
||||
2. Read ROADMAP.md → Determine phases, find current position
|
||||
3. Scan \*-SUMMARY.md files → Extract decisions, issues, concerns
|
||||
4. Read ISSUES.md → Count deferred issues
|
||||
3. Scan \*-SUMMARY.md files → Extract decisions, concerns
|
||||
4. Count pending todos in .planning/todos/pending/
|
||||
5. Check for .continue-here files → Session continuity
|
||||
|
||||
Reconstruct and write STATE.md, then proceed normally.
|
||||
|
||||
@@ -342,12 +342,6 @@ Review and update Accumulated Context section in STATE.md.
|
||||
- If still relevant for future: Keep with "Phase X" prefix
|
||||
- Add any new concerns from completed phase's summaries
|
||||
|
||||
**Deferred Issues:**
|
||||
|
||||
- Count open issues in ISSUES.md
|
||||
- Update count: "[N] open issues — see ISSUES.md"
|
||||
- If many accumulated, note: "Consider addressing ISS-XXX, ISS-YYY in next phase"
|
||||
|
||||
**Example:**
|
||||
|
||||
Before:
|
||||
@@ -357,10 +351,6 @@ Before:
|
||||
|
||||
- ⚠️ [Phase 1] Database schema not indexed for common queries
|
||||
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
- ISS-001: Rate limiting on sync endpoint (Phase 2) — Medium
|
||||
```
|
||||
|
||||
After (if database indexing was addressed in Phase 2):
|
||||
@@ -369,11 +359,6 @@ After (if database indexing was addressed in Phase 2):
|
||||
### Blockers/Concerns
|
||||
|
||||
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
- ISS-001: Rate limiting on sync endpoint (Phase 2) — Medium
|
||||
- ISS-002: Better sync error messages (Phase 2) — Quick
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
@@ -382,7 +367,6 @@ After (if database indexing was addressed in Phase 2):
|
||||
- [ ] Resolved blockers removed from list
|
||||
- [ ] Unresolved blockers kept with phase prefix
|
||||
- [ ] New concerns from completed phase added
|
||||
- [ ] Deferred issues count updated
|
||||
|
||||
</step>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user