get-shit-done-cc 1.5.28 → 1.5.30

package/commands/gsd/progress.md

@@ -193,14 +193,14 @@ Check if `{phase}-CONTEXT.md` exists in phase directory.
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 
-`/gsd:plan-phase {phase}`
+`/gsd:discuss-phase {phase}` — gather context and clarify approach
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/gsd:discuss-phase {phase}` — gather context first
+- `/gsd:plan-phase {phase}` — skip discussion, plan directly
 - `/gsd:list-phase-assumptions {phase}` — see Claude's assumptions
 
 ---
@@ -266,15 +266,15 @@ Read ROADMAP.md to get the next phase's name and goal.
 
 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
 
-`/gsd:plan-phase {Z+1}`
+`/gsd:discuss-phase {Z+1}` — gather context and clarify approach
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
+- `/gsd:plan-phase {Z+1}` — skip discussion, plan directly
 - `/gsd:verify-work {Z}` — user acceptance test before continuing
-- `/gsd:discuss-phase {Z+1}` — gather context first
 
 ---
 ```

package/commands/gsd/research-phase.md

@@ -26,17 +26,23 @@ Research how to implement a phase. Spawns gsd-phase-researcher agent with phase
 <context>
 Phase number: $ARGUMENTS (required)
 
-Check for existing research:
-```bash
-ls .planning/phases/${PHASE}-*/*RESEARCH.md 2>/dev/null
-```
+Normalize phase input in step 1 before any directory lookups.
 </context>
 
 <process>
 
-## 1. Parse and Validate Phase
+## 1. Normalize and Validate Phase
 
 ```bash
+# Normalize phase number (8 → 08, but preserve decimals like 2.1 → 02.1)
+if [[ "$ARGUMENTS" =~ ^[0-9]+$ ]]; then
+  PHASE=$(printf "%02d" "$ARGUMENTS")
+elif [[ "$ARGUMENTS" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+else
+  PHASE="$ARGUMENTS"
+fi
+
 grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
 ```
 
@@ -118,7 +124,7 @@ Before declaring complete, verify:
 </quality_gate>
 
 <output>
-Write to: .planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
 </output>
 ```
 
@@ -146,7 +152,7 @@ Continue research for Phase {phase_number}: {phase_name}
 </objective>
 
 <prior_state>
-Research file: @.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
+Research file: @.planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
 </prior_state>
 
 <checkpoint_response>

package/commands/gsd/verify-work.md

@@ -9,14 +9,15 @@ allowed-tools:
   - Grep
   - Edit
   - Write
+  - Task
 ---
 
 <objective>
 Validate built features through conversational testing with persistent state.
 
-Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation.
+Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for execution.
 
-Output: {phase}-UAT.md tracking all test results, gaps logged for /gsd:plan-phase --gaps
+Output: {phase}-UAT.md tracking all test results. If issues found: diagnosed gaps, verified fix plans ready for /gsd:execute-phase
 </objective>
 
 <execution_context>
@@ -43,7 +44,13 @@ Phase: $ARGUMENTS (optional)
    - Wait for plain text response
    - "yes/y/next" = pass, anything else = issue (severity inferred)
 6. Update UAT.md after each response
-7. On completion: commit, present summary, offer next steps
+7. On completion: commit, present summary
+8. If issues found:
+   - Spawn parallel debug agents to diagnose root causes
+   - Spawn gsd-planner in --gaps mode to create fix plans
+   - Spawn gsd-plan-checker to verify fix plans
+   - Iterate planner ↔ checker until plans pass (max 3)
+   - Present ready status with `/clear` then `/gsd:execute-phase`
 </process>
 
 <anti_patterns>
@@ -51,7 +58,7 @@ Phase: $ARGUMENTS (optional)
 - Don't ask severity — infer from description
 - Don't present full checklist upfront — one test at a time
 - Don't run automated tests — this is manual user validation
-- Don't fix issues during testing — log as gaps for /gsd:plan-phase --gaps
+- Don't fix issues during testing — log as gaps, diagnose after all tests complete
 </anti_patterns>
 
 <success_criteria>
@@ -61,5 +68,8 @@ Phase: $ARGUMENTS (optional)
 - [ ] Severity inferred, never asked
 - [ ] Batched writes: on issue, every 5 passes, or completion
 - [ ] Committed on completion
-- [ ] Clear next steps based on results
+- [ ] If issues: parallel debug agents diagnose root causes
+- [ ] If issues: gsd-planner creates fix plans from diagnosed gaps
+- [ ] If issues: gsd-plan-checker verifies fix plans (max 3 iterations)
+- [ ] Ready for `/gsd:execute-phase` when complete
 </success_criteria>

package/get-shit-done/templates/context.md

@@ -4,6 +4,8 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
 
 **Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
 
+**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
 **Downstream consumers:**
 - `gsd-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
 - `gsd-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
@@ -28,11 +30,14 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
 <decisions>
 ## Implementation Decisions
 
-### [Category discussed, e.g., UI]
+### [Area 1 that was discussed]
 - [Specific decision made]
 - [Another decision if applicable]
 
-### [Category discussed, e.g., Behavior]
+### [Area 2 that was discussed]
+- [Specific decision made]
+
+### [Area 3 that was discussed]
 - [Specific decision made]
 
 ### Claude's Discretion
@@ -65,6 +70,9 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
 ```
 
 <good_examples>
+
+**Example 1: Visual feature (Post Feed)**
+
 ```markdown
 # Phase 3: Post Feed - Context
 
@@ -81,18 +89,17 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 <decisions>
 ## Implementation Decisions
 
-### UI
+### Layout style
 - Card-based layout, not timeline or list
 - Each card shows: author avatar, name, timestamp, full post content, reaction counts
 - Cards have subtle shadows, rounded corners — modern feel
-- Show 10 posts initially, load more on scroll
 
-### Behavior
+### Loading behavior
 - Infinite scroll, not pagination
 - Pull-to-refresh on mobile
 - New posts indicator at top ("3 new posts") rather than auto-inserting
 
-### Empty State
+### Empty state
 - Friendly illustration + "Follow people to see posts here"
 - Suggest 3-5 accounts to follow based on interests
 
@@ -108,7 +115,6 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 
 - "I like how Twitter shows the new posts indicator without disrupting your scroll position"
 - Cards should feel like Linear's issue cards — clean, not cluttered
-- No infinite scroll fatigue — maybe show "You're all caught up" after ~50 posts
 
 </specifics>
 
@@ -116,7 +122,6 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 ## Deferred Ideas
 
 - Commenting on posts — Phase 5
-- Reaction picker (not just counts) — Phase 5
 - Bookmarking posts — add to backlog
 
 </deferred>
@@ -126,6 +131,131 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 *Phase: 03-post-feed*
 *Context gathered: 2025-01-20*
 ```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### Claude's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 02-backup-command*
+*Context gathered: 2025-01-20*
+```
+
+**Example 3: Organization task (Photo library)**
+
+```markdown
+# Phase 1: Photo Organization - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Grouping criteria
+- Primary grouping by year, then by month
+- Events detected by time clustering (photos within 2 hours = same event)
+- Event folders named by date + location if available
+
+### Duplicate handling
+- Keep highest resolution version
+- Move duplicates to _duplicates folder (don't delete)
+- Log all duplicate decisions for review
+
+### Naming convention
+- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
+- Preserve original filename as suffix for searchability
+- Handle name collisions with incrementing suffix
+
+### Claude's Discretion
+- Exact clustering algorithm
+- How to handle photos with no EXIF data
+- Folder emoji usage
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want to be able to find photos by roughly when they were taken"
+- Don't delete anything — worst case, move to a review folder
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Face detection grouping — future phase
+- Cloud sync — out of scope for now
+
+</deferred>
+
+---
+
+*Phase: 01-photo-organization*
+*Context gathered: 2025-01-20*
+```
+
 </good_examples>
 
 <guidelines>
@@ -133,11 +263,11 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 
 The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
 
-**Good content:**
+**Good content (concrete decisions):**
 - "Card-based layout, not timeline"
-- "Infinite scroll with pull-to-refresh"
-- "Show 10 posts initially"
-- "New posts indicator rather than auto-insert"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
 
 **Bad content (too vague):**
 - "Should feel modern and clean"
@@ -148,7 +278,7 @@ The output should answer: "What does the researcher need to investigate? What ch
 **Sections explained:**
 
 - **Domain** — The scope anchor. Copied/derived from ROADMAP.md. Fixed boundary.
-- **Decisions** — Organized by category (UI, UX, Behavior, etc.). Actual choices made.
+- **Decisions** — Organized by areas discussed (NOT predefined categories). Section headers come from the actual discussion — "Layout style", "Flag design", "Grouping criteria", etc.
 - **Claude's Discretion** — Explicit acknowledgment of what Claude can decide during implementation.
 - **Specifics** — Product references, examples, "like X but..." statements.
 - **Deferred** — Ideas captured but explicitly out of scope. Prevents scope creep while preserving good ideas.

package/get-shit-done/workflows/create-roadmap.md

@@ -577,14 +577,14 @@ Project initialized:
 
 **Phase 1: [Name]** — [Goal from ROADMAP.md]
 
-`/gsd:plan-phase 1`
+`/gsd:discuss-phase 1` — gather context and clarify approach
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/gsd:discuss-phase 1` — gather context first
+- `/gsd:plan-phase 1` — skip discussion, plan directly
 - Review roadmap
 
 ---

package/get-shit-done/workflows/diagnose-issues.md

@@ -164,10 +164,13 @@ git commit -m "docs({phase}): add root causes from diagnosis"
 </step>
 
 <step name="report_results">
-**Report diagnosis results:**
+**Report diagnosis results and hand off:**
 
+Display:
 ```
-## Diagnosis Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► DIAGNOSIS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 | Gap (Truth) | Root Cause | Files |
 |-------------|------------|-------|
@@ -175,26 +178,13 @@ git commit -m "docs({phase}): add root causes from diagnosis"
 | Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
 | Delete removes comment | API missing auth header | api/comments.ts |
 
-Debug sessions saved to ${DEBUG_DIR}/
+Debug sessions: ${DEBUG_DIR}/
 
----
-
-Next steps:
-- `/gsd:plan-phase {phase} --gaps` — Create fix plans from diagnosed gaps
-- Review debug sessions for details
+Proceeding to plan fixes...
 ```
-</step>
 
-<step name="offer_next">
-**Offer gap closure:**
-
-```
-Root causes identified. Ready to plan fixes?
-
-`/gsd:plan-phase {phase} --gaps`
-
-The fix plans will use diagnosed root causes for targeted fixes.
-```
+Return to verify-work orchestrator for automatic planning.
+Do NOT offer manual next steps - verify-work handles the rest.
 </step>
 
 </process>
@@ -239,5 +229,5 @@ The fix plans will use diagnosed root causes for targeted fixes.
 - [ ] Root causes collected from all agents
 - [ ] UAT.md gaps updated with artifacts and missing
 - [ ] Debug sessions saved to ${DEBUG_DIR}/
-- [ ] User knows next steps (plan-phase --gaps)
+- [ ] Hand off to verify-work for automatic planning
 </success_criteria>

package/get-shit-done/workflows/discuss-phase.md

@@ -66,23 +66,44 @@ For now, let's focus on [phase domain]."
 Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
 </scope_guardrail>
 
-<gray_area_categories>
-Use these categories when analyzing a phase. Not all apply to every phase.
-
-| Category | What it clarifies | Example questions |
-|----------|-------------------|-------------------|
-| **UI** | Visual presentation, layout, information density | "Card-based or list view?" "What info shows on each item?" |
-| **UX** | Interactions, flows, feedback | "How does loading work?" "What happens when you tap X?" |
-| **Behavior** | Runtime behavior, state changes | "Auto-refresh or manual?" "How does pagination work?" |
-| **Empty/Edge States** | What shows in unusual situations | "What appears with no data?" "How do errors display?" |
-| **Content** | What information is shown/hidden | "Show timestamps?" "How much preview text?" |
-
-**Categories to AVOID:**
-- **Scope** — The roadmap defines scope, not discussion
-- **Technical** — You figure out implementation
-- **Architecture** — You decide patterns
-- **Performance** — You handle optimization
-</gray_area_categories>
+<gray_area_identification>
+Gray areas are **implementation decisions the user cares about** — things that could go multiple ways and would change the result.
+
+**How to identify gray areas:**
+
+1. **Read the phase goal** from ROADMAP.md
+2. **Understand the domain** — What kind of thing is being built?
+   - Something users SEE → visual presentation, interactions, states matter
+   - Something users CALL → interface contracts, responses, errors matter
+   - Something users RUN → invocation, output, behavior modes matter
+   - Something users READ → structure, tone, depth, flow matter
+   - Something being ORGANIZED → criteria, grouping, handling exceptions matter
+3. **Generate phase-specific gray areas** — Not generic categories, but concrete decisions for THIS phase
+
+**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:
+
+```
+Phase: "User authentication"
+→ Session handling, Error responses, Multi-device policy, Recovery flow
+
+Phase: "Organize photo library"
+→ Grouping criteria, Duplicate handling, Naming convention, Folder structure
+
+Phase: "CLI for database backups"
+→ Output format, Flag design, Progress reporting, Error recovery
+
+Phase: "API documentation"
+→ Structure/navigation, Code examples depth, Versioning approach, Interactive elements
+```
+
+**The key question:** What decisions would change the outcome that the user should weigh in on?
+
+**Claude handles these (don't ask):**
+- Technical implementation details
+- Architecture patterns
+- Performance optimization
+- Scope (roadmap defines this)
+</gray_area_identification>
 
 <process>
 
@@ -169,47 +190,79 @@ We'll clarify HOW to implement this.
 
 **Then use AskUserQuestion (multiSelect: true):**
 - header: "Discuss"
-- question: "Which areas do you want to discuss?"
-- options: Generate 2-4 based on your analysis, each formatted as:
-  - "[Category] — [Specific gray area question]"
-  - Last option always: "None — you decide, proceed to planning"
+- question: "Which areas do you want to discuss for [phase name]?"
+- options: Generate 3-4 phase-specific gray areas, each formatted as:
+  - "[Specific area]" (label) — concrete, not generic
+  - [1-2 questions this covers] (description)
+
+**Do NOT include a "skip" or "you decide" option.** User ran this command to discuss — give them real choices.
 
-**Example options:**
+**Examples by domain:**
+
+For "Post Feed" (visual feature):
+```
+☐ Layout style — Cards vs list vs timeline? Information density?
+☐ Loading behavior — Infinite scroll or pagination? Pull to refresh?
+☐ Content ordering — Chronological, algorithmic, or user choice?
+☐ Post metadata — What info per post? Timestamps, reactions, author?
+```
+
+For "Database backup CLI" (command-line tool):
+```
+☐ Output format — JSON, table, or plain text? Verbosity levels?
+☐ Flag design — Short flags, long flags, or both? Required vs optional?
+☐ Progress reporting — Silent, progress bar, or verbose logging?
+☐ Error recovery — Fail fast, retry, or prompt for action?
+```
+
+For "Organize photo library" (organization task):
 ```
-☐ UI — Card layout or timeline? How much of each post shows?
-☐ Behavior — Infinite scroll or pagination? Pull to refresh?
-☐ Empty state — What appears when there are no posts?
-☐ None — You decide, proceed to planning
+☐ Grouping criteria — By date, location, faces, or events?
+☐ Duplicate handling — Keep best, keep all, or prompt each time?
+☐ Naming convention — Original names, dates, or descriptive?
+☐ Folder structure — Flat, nested by year, or by category?
 ```
 
-If user selects "None": Skip to write_context with minimal context.
-Otherwise: Continue to discuss_areas with selected areas.
+Continue to discuss_areas with selected areas.
 </step>
 
 <step name="discuss_areas">
 For each selected area, conduct a focused discussion loop.
 
+**Philosophy: 4 questions, then check.**
+
+Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.
+
 **For each area:**
 
 1. **Announce the area:**
    ```
-   Let's talk about [Category].
+   Let's talk about [Area].
    ```
 
-2. **Ask focused questions using AskUserQuestion:**
-   - header: "[Category]"
-   - question: Specific question about that gray area
-   - options: 2-3 concrete choices + "Let me describe" + "You decide"
+2. **Ask 4 questions using AskUserQuestion:**
+   - header: "[Area]"
+   - question: Specific decision for this area
+   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically)
+   - Include "You decide" as an option when reasonable — captures Claude discretion
 
-3. **Follow up based on response:**
-   - If they chose an option: Capture it, ask if there's more about this area
-   - If "Let me describe": Receive their input, reflect it back, confirm understanding
-   - If "You decide": Note that Claude has discretion here
+3. **After 4 questions, check:**
+   - header: "[Area]"
+   - question: "More questions about [area], or move to next?"
+   - options: "More questions" / "Next area"
 
-4. **Loop control — Always offer:**
-   - "Ask more about [Category]" — Continue probing this area
-   - "Move to next area" — Done with this category
-   - "That's enough, create context" — Done with all discussion
+   If "More questions" → ask 4 more, then check again
+   If "Next area" → proceed to next selected area
+
+4. **After all areas complete:**
+   - header: "Done"
+   - question: "That covers [list areas]. Ready to create context?"
+   - options: "Create context" / "Revisit an area"
+
+**Question design:**
+- Options should be concrete, not abstract ("Cards" not "Option A")
+- Each answer should inform the next question
+- If user picks "Other", receive their input, reflect it back, confirm
 
 **Scope creep handling:**
 If user mentions something outside the phase domain:
@@ -217,14 +270,10 @@ If user mentions something outside the phase domain:
 "[Feature] sounds like a new capability — that belongs in its own phase.
 I'll note it as a deferred idea.
 
-Back to [current domain]: [return to current question]"
+Back to [current area]: [return to current question]"
 ```
 
 Track deferred ideas internally.
-
-**Continue until:**
-- User says "Move to next area" and all selected areas are done, OR
-- User says "That's enough, create context"
 </step>
 
 <step name="write_context">