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
@@ -251,7 +251,6 @@ 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 |
|
||||
| `todos/` | Captured ideas and tasks for later work |
|
||||
|
||||
Size limits based on where Claude's quality degrades. Stay under, get consistent excellence.
|
||||
@@ -342,7 +341,6 @@ 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:add-todo [desc]` | Capture idea or task from conversation for later |
|
||||
| `/gsd:check-todos [area]` | List pending todos, select one to work on |
|
||||
| `/gsd:debug [desc]` | Systematic debugging with persistent state across `/clear` |
|
||||
|
||||
@@ -81,7 +81,6 @@ During execution, handle discoveries automatically:
|
||||
2. **Auto-add critical** - Security/correctness gaps, add and document
|
||||
3. **Auto-fix blockers** - Can't proceed without fix, do it and document
|
||||
4. **Ask about architectural** - Major structural changes, stop and ask user
|
||||
5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
|
||||
|
||||
Only rule 4 requires user intervention.
|
||||
</deviation_rules>
|
||||
|
||||
@@ -1,202 +0,0 @@
|
||||
---
|
||||
name: gsd:consider-issues
|
||||
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>
|
||||
@.planning/ISSUES.md
|
||||
@.planning/STATE.md
|
||||
@.planning/ROADMAP.md
|
||||
</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:**
|
||||
- Display the command for user to run after clearing: `/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>
|
||||
@@ -99,7 +99,6 @@ During execution, handle discoveries automatically:
|
||||
2. **Auto-add critical** - Security/correctness gaps, add and document
|
||||
3. **Auto-fix blockers** - Can't proceed without fix, do it and document
|
||||
4. **Ask about architectural** - Major structural changes, stop and ask user
|
||||
5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
|
||||
|
||||
Only rule 4 requires user intervention.
|
||||
</deviation_rules>
|
||||
|
||||
@@ -235,19 +235,6 @@ 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`
|
||||
|
||||
### Debugging
|
||||
|
||||
**`/gsd:debug [issue description]`**
|
||||
@@ -300,7 +287,6 @@ 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
|
||||
├── todos/ # Captured ideas and tasks
|
||||
│ ├── pending/ # Todos waiting to be worked on
|
||||
|
||||
@@ -55,7 +55,7 @@ If missing STATE.md or ROADMAP.md: inform what's missing, suggest running `/gsd:
|
||||
|
||||
- From STATE.md: current phase, plan number, status
|
||||
- Calculate: total plans, completed plans, remaining plans
|
||||
- Note any blockers, concerns, or deferred issues
|
||||
- Note any blockers or concerns
|
||||
- Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory
|
||||
- Count pending todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l`
|
||||
- Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
|
||||
@@ -82,8 +82,8 @@ CONTEXT: [✓ if CONTEXT.md exists | - if not]
|
||||
- [decision 1 from STATE.md]
|
||||
- [decision 2]
|
||||
|
||||
## Open Issues
|
||||
- [any deferred issues or blockers]
|
||||
## Blockers/Concerns
|
||||
- [any blockers or concerns from STATE.md]
|
||||
|
||||
## Pending Todos
|
||||
- [count] pending — /gsd:check-todos to review
|
||||
|
||||
@@ -243,15 +243,3 @@ skipped: 0
|
||||
root_cause: useEffect in CommentList.tsx missing commentCount dependency
|
||||
```
|
||||
</good_example>
|
||||
|
||||
<difference_from_issues_md>
|
||||
|
||||
| UAT.md | ISSUES.md (global) |
|
||||
|--------|-------------------|
|
||||
| Created by /gsd:verify-work | Created by deviation rule 5 during execution |
|
||||
| Tracks test session state | Tracks deferred enhancements |
|
||||
| Phase-scoped, one per phase | Global, one per project |
|
||||
| Feeds into /gsd:plan-fix | Feeds into /gsd:consider-issues |
|
||||
| Contains pass/fail/skip results | Contains only deferred items |
|
||||
|
||||
</difference_from_issues_md>
|
||||
|
||||
@@ -1,32 +0,0 @@
|
||||
# Project Issues Log
|
||||
|
||||
Enhancements discovered during execution. Not critical - address in future phases.
|
||||
|
||||
## Open Enhancements
|
||||
|
||||
### ISS-001: [Brief description]
|
||||
|
||||
- **Discovered:** Phase [X] Task [Z] (YYYY-MM-DD)
|
||||
- **Type:** [Performance / Refactoring / UX / Testing / Documentation / Accessibility]
|
||||
- **Description:** [What could be improved and why it would help]
|
||||
- **Impact:** Low (works correctly, this would enhance)
|
||||
- **Effort:** [Quick / Medium / Substantial]
|
||||
- **Suggested phase:** [Phase number or "Future"]
|
||||
|
||||
## Closed Enhancements
|
||||
|
||||
[Moved here when addressed]
|
||||
|
||||
---
|
||||
|
||||
## Template Notes
|
||||
|
||||
**When to create:** First time Rule 5 (log enhancements) triggers during execution.
|
||||
|
||||
**Location:** `.planning/ISSUES.md`
|
||||
|
||||
**ISS numbering:** Auto-increment from highest existing number.
|
||||
|
||||
**Entry format:** Copy the ISS-001 block, update number and fields.
|
||||
|
||||
**Closing issues:** Move entire block to "Closed Enhancements" section, add resolution note.
|
||||
@@ -54,12 +54,6 @@ Recent decisions affecting current work:
|
||||
- [Phase X]: [Decision summary]
|
||||
- [Phase Y]: [Decision summary]
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
[From ISSUES.md — list open items with phase of origin]
|
||||
|
||||
None yet.
|
||||
|
||||
### Pending Todos
|
||||
|
||||
[From .planning/todos/pending/ — ideas captured during sessions]
|
||||
@@ -110,7 +104,6 @@ STATE.md is the project's short-term memory spanning all phases and sessions.
|
||||
- execute: After SUMMARY.md created
|
||||
- Update position (phase, plan, status)
|
||||
- Note new decisions (detail in PROJECT.md)
|
||||
- Update deferred issues list
|
||||
- Add blockers/concerns
|
||||
- transition: After phase marked complete
|
||||
- Update progress bar
|
||||
@@ -152,12 +145,6 @@ Updated after each plan completion.
|
||||
|
||||
**Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
|
||||
|
||||
**Deferred Issues:** Open items from ISSUES.md
|
||||
- Brief description with ISS-XXX number
|
||||
- Phase where discovered
|
||||
- Effort estimate if known
|
||||
- Helps phase planning identify what to address
|
||||
|
||||
**Pending Todos:** Ideas captured via /gsd:add-todo
|
||||
- Count of pending todos
|
||||
- Reference to .planning/todos/pending/
|
||||
@@ -182,7 +169,6 @@ Keep STATE.md under 100 lines.
|
||||
|
||||
It's a DIGEST, not an archive. If accumulated context grows too large:
|
||||
- Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
|
||||
- Reference ISSUES.md instead of listing all: "12 open issues — see ISSUES.md"
|
||||
- Keep only active blockers, remove resolved ones
|
||||
|
||||
The goal is "read once, know where we are" — if it's too long, that fails.
|
||||
@@ -208,14 +194,13 @@ The goal is "read once, know where we are" — if it's too long, that fails.
|
||||
**Size management:**
|
||||
- Keep under 100 lines total
|
||||
- Recent decisions only in STATE.md (full log in PROJECT.md)
|
||||
- Reference ISSUES.md instead of listing all issues
|
||||
- Keep only active blockers
|
||||
|
||||
**Sections:**
|
||||
- Project Reference: Pointer to PROJECT.md with core value
|
||||
- Current Position: Where we are now (phase, plan, status)
|
||||
- Performance Metrics: Velocity tracking
|
||||
- Accumulated Context: Recent decisions, deferred issues, blockers
|
||||
- Accumulated Context: Recent decisions, pending todos, blockers
|
||||
- Session Continuity: Resume information
|
||||
|
||||
</guidelines>
|
||||
|
||||
@@ -38,8 +38,6 @@ patterns-established:
|
||||
- "Pattern 1: description"
|
||||
- "Pattern 2: description"
|
||||
|
||||
issues-created: [ISS-XXX, ISS-YYY] # From ISSUES.md if any
|
||||
|
||||
# Metrics
|
||||
duration: Xmin
|
||||
completed: YYYY-MM-DD
|
||||
@@ -99,15 +97,9 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
|
||||
|
||||
[... repeat for each auto-fix ...]
|
||||
|
||||
### Deferred Enhancements
|
||||
|
||||
Logged to .planning/ISSUES.md for future consideration:
|
||||
- ISS-XXX: [Brief description] (discovered in Task [N])
|
||||
- ISS-XXX: [Brief description] (discovered in Task [N])
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** [N] auto-fixed ([breakdown by rule]), [N] deferred
|
||||
**Total deviations:** [N] auto-fixed ([breakdown by rule])
|
||||
**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for correctness/security. No scope creep."]
|
||||
|
||||
## Issues Encountered
|
||||
@@ -211,15 +203,9 @@ The one-liner should tell someone what actually shipped.
|
||||
- **Verification:** Import succeeds, build passes
|
||||
- **Committed in:** def456g (Task 4 commit)
|
||||
|
||||
### Deferred Enhancements
|
||||
|
||||
Logged to .planning/ISSUES.md for future consideration:
|
||||
- ISS-001: Add rate limiting to login endpoint (discovered in Task 2)
|
||||
- ISS-002: Improve token refresh UX with auto-retry on 401 (discovered in Task 5)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 2 auto-fixed (1 missing critical, 1 blocking), 2 deferred
|
||||
**Total deviations:** 2 auto-fixed (1 missing critical, 1 blocking)
|
||||
**Impact on plan:** Both auto-fixes essential for security and functionality. No scope creep.
|
||||
|
||||
## Issues Encountered
|
||||
@@ -259,7 +245,6 @@ Logged to .planning/ISSUES.md for future consideration:
|
||||
- Documents unplanned work handled via deviation rules
|
||||
- Separate from "Issues Encountered" (which is planned work problems)
|
||||
- Auto-fixed issues: What was wrong, how fixed, verification
|
||||
- Deferred enhancements: Logged to ISSUES.md with ISS-XXX numbers
|
||||
|
||||
**Decisions section:**
|
||||
- Key decisions made during execution
|
||||
|
||||
@@ -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