feat(verification): add verify → plan → execute loop for gap closure
- Add verify_phase_goal step to execute-phase workflow - Verifier outputs structured gaps: YAML for planner consumption - Add --gaps flag to plan-phase for gap closure mode - Route by verification status: passed, gaps_found, human_needed - Gap closure creates sequential plans (04, 05...) from verification gaps - User stays in control at each decision point Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -462,48 +462,51 @@ Some things can't be verified programmatically:
|
||||
score = (verified_truths / total_truths)
|
||||
```
|
||||
|
||||
## Step 10: Generate Fix Plans (If Gaps Found)
|
||||
## Step 10: Structure Gap Output (If Gaps Found)
|
||||
|
||||
Group related gaps into fix plans:
|
||||
When gaps are found, structure them for consumption by `/gsd:plan-phase --gaps`.
|
||||
|
||||
1. **Identify gap clusters:**
|
||||
**Output structured gaps in YAML frontmatter:**
|
||||
|
||||
- API stub + component not wired → "Wire frontend to backend"
|
||||
- Multiple artifacts missing → "Complete core implementation"
|
||||
- Wiring issues only → "Connect existing components"
|
||||
|
||||
2. **Generate plan recommendations:**
|
||||
|
||||
```markdown
|
||||
### {phase}-{next}-PLAN.md: {Fix Name}
|
||||
|
||||
**Objective:** {What this fixes}
|
||||
|
||||
**Tasks:**
|
||||
|
||||
1. {Task to fix gap 1}
|
||||
|
||||
- Files: {files to modify}
|
||||
- Action: {specific fix}
|
||||
- Verify: {how to confirm fix}
|
||||
|
||||
2. {Task to fix gap 2}
|
||||
|
||||
3. Re-verify phase goal
|
||||
|
||||
**Estimated scope:** {Small / Medium}
|
||||
```yaml
|
||||
---
|
||||
phase: XX-name
|
||||
verified: YYYY-MM-DDTHH:MM:SSZ
|
||||
status: gaps_found
|
||||
score: N/M must-haves verified
|
||||
gaps:
|
||||
- truth: "User can see existing messages"
|
||||
status: failed
|
||||
reason: "Chat.tsx exists but doesn't fetch from API"
|
||||
artifacts:
|
||||
- path: "src/components/Chat.tsx"
|
||||
issue: "No useEffect with fetch call"
|
||||
missing:
|
||||
- "API call in useEffect to /api/chat"
|
||||
- "State for storing fetched messages"
|
||||
- "Render messages array in JSX"
|
||||
- truth: "User can send a message"
|
||||
status: failed
|
||||
reason: "Form exists but onSubmit is stub"
|
||||
artifacts:
|
||||
- path: "src/components/Chat.tsx"
|
||||
issue: "onSubmit only calls preventDefault()"
|
||||
missing:
|
||||
- "POST request to /api/chat"
|
||||
- "Add new message to state after success"
|
||||
---
|
||||
```
|
||||
|
||||
3. **Keep plans focused:**
|
||||
**Gap structure:**
|
||||
- `truth`: The observable truth that failed verification
|
||||
- `status`: failed | partial
|
||||
- `reason`: Brief explanation of why it failed
|
||||
- `artifacts`: Which files have issues and what's wrong
|
||||
- `missing`: Specific things that need to be added/fixed
|
||||
|
||||
- 2-3 tasks per plan
|
||||
- Single concern per plan
|
||||
- Include verification task
|
||||
The planner (`/gsd:plan-phase --gaps`) reads this gap analysis and creates appropriate plans.
|
||||
|
||||
4. **Order by dependency:**
|
||||
- Fix missing artifacts before wiring
|
||||
- Fix stubs before integration
|
||||
- Verify after all fixes
|
||||
**Group related gaps by concern** when possible — if multiple truths fail because of the same root cause (e.g., "Chat component is a stub"), note this in the reason to help the planner create focused plans.
|
||||
|
||||
</verification_process>
|
||||
|
||||
@@ -519,6 +522,20 @@ phase: XX-name
|
||||
verified: YYYY-MM-DDTHH:MM:SSZ
|
||||
status: passed | gaps_found | human_needed
|
||||
score: N/M must-haves verified
|
||||
gaps: # Only include if status: gaps_found
|
||||
- truth: "Observable truth that failed"
|
||||
status: failed
|
||||
reason: "Why it failed"
|
||||
artifacts:
|
||||
- path: "src/path/to/file.tsx"
|
||||
issue: "What's wrong with this file"
|
||||
missing:
|
||||
- "Specific thing to add/fix"
|
||||
- "Another specific thing"
|
||||
human_verification: # Only include if status: human_needed
|
||||
- test: "What to do"
|
||||
expected: "What should happen"
|
||||
why_human: "Why can't verify programmatically"
|
||||
---
|
||||
|
||||
# Phase {X}: {Name} Verification Report
|
||||
@@ -561,15 +578,11 @@ score: N/M must-haves verified
|
||||
|
||||
### Human Verification Required
|
||||
|
||||
{Items needing human testing}
|
||||
{Items needing human testing — detailed format for user}
|
||||
|
||||
### Gaps Summary
|
||||
|
||||
{Critical and non-critical gaps}
|
||||
|
||||
### Recommended Fix Plans
|
||||
|
||||
{If gaps_found, include fix plan recommendations}
|
||||
{Narrative summary of what's missing and why}
|
||||
|
||||
---
|
||||
|
||||
@@ -597,17 +610,14 @@ All must-haves verified. Phase goal achieved. Ready to proceed.
|
||||
|
||||
### Gaps Found
|
||||
|
||||
{N} critical gaps blocking goal achievement:
|
||||
{N} gaps blocking goal achievement:
|
||||
|
||||
1. {Gap 1 summary}
|
||||
2. {Gap 2 summary}
|
||||
1. **{Truth 1}** — {reason}
|
||||
- Missing: {what needs to be added}
|
||||
2. **{Truth 2}** — {reason}
|
||||
- Missing: {what needs to be added}
|
||||
|
||||
### Recommended Fixes
|
||||
|
||||
{N} fix plans recommended:
|
||||
|
||||
1. {phase}-{next}-PLAN.md: {name}
|
||||
2. {phase}-{next+1}-PLAN.md: {name}
|
||||
Structured gaps in VERIFICATION.md frontmatter for `/gsd:plan-phase --gaps`.
|
||||
|
||||
{If human_needed:}
|
||||
|
||||
@@ -615,8 +625,10 @@ All must-haves verified. Phase goal achieved. Ready to proceed.
|
||||
|
||||
{N} items need human testing:
|
||||
|
||||
1. {Item 1}
|
||||
2. {Item 2}
|
||||
1. **{Test name}** — {what to do}
|
||||
- Expected: {what should happen}
|
||||
2. **{Test name}** — {what to do}
|
||||
- Expected: {what should happen}
|
||||
|
||||
Automated checks passed. Awaiting human verification.
|
||||
```
|
||||
@@ -631,7 +643,7 @@ Automated checks passed. Awaiting human verification.
|
||||
|
||||
**DO NOT skip key link verification.** This is where 80% of stubs hide. The pieces exist but aren't connected.
|
||||
|
||||
**DO generate fix plans if gaps found.** Don't just report "this is broken" — recommend specific fix plans with tasks.
|
||||
**Structure gaps in YAML frontmatter.** The planner (`/gsd:plan-phase --gaps`) creates plans from your analysis.
|
||||
|
||||
**DO flag for human verification when uncertain.** If you can't verify programmatically (visual, real-time, external service), say so explicitly.
|
||||
|
||||
@@ -726,7 +738,7 @@ return <div>No messages</div> // Always shows "no messages"
|
||||
- [ ] Anti-patterns scanned and categorized
|
||||
- [ ] Human verification items identified
|
||||
- [ ] Overall status determined
|
||||
- [ ] Fix plans generated (if gaps_found)
|
||||
- [ ] Gaps structured in YAML frontmatter (if gaps_found)
|
||||
- [ ] VERIFICATION.md created with complete report
|
||||
- [ ] Results returned to orchestrator (NOT committed)
|
||||
</success_criteria>
|
||||
</success_criteria>
|
||||
|
||||
@@ -65,9 +65,10 @@ Phase: $ARGUMENTS
|
||||
- Spawn `gsd-verifier` subagent with phase directory and goal
|
||||
- Verifier checks must_haves against actual codebase (not SUMMARY claims)
|
||||
- Creates VERIFICATION.md with detailed report
|
||||
- If gaps found: create fix plans, execute, re-verify (max 3 cycles)
|
||||
- If human verification needed: present items to user
|
||||
- Block until verification passes or user approves
|
||||
- Route by status:
|
||||
- `passed` → continue to step 7
|
||||
- `human_needed` → present items, get approval or feedback
|
||||
- `gaps_found` → present gaps, offer `/gsd:plan-phase {X} --gaps`
|
||||
|
||||
7. **Update roadmap and state**
|
||||
- Update ROADMAP.md, STATE.md
|
||||
@@ -93,25 +94,23 @@ Phase: $ARGUMENTS
|
||||
<offer_next>
|
||||
**MANDATORY: Present copy/paste-ready next command.**
|
||||
|
||||
After phase completes, determine what's next:
|
||||
After verification completes, route based on status:
|
||||
|
||||
**Step 1: Check milestone status**
|
||||
|
||||
Read ROADMAP.md. Find current phase number and highest phase in milestone.
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| current < highest | More phases → Route A |
|
||||
| current = highest | Milestone complete → Route B |
|
||||
| Status | Route |
|
||||
|--------|-------|
|
||||
| `gaps_found` | Route C (gap closure) |
|
||||
| `human_needed` | Present checklist, then re-route based on approval |
|
||||
| `passed` + more phases | Route A (next phase) |
|
||||
| `passed` + last phase | Route B (milestone complete) |
|
||||
|
||||
---
|
||||
|
||||
**Route A: More phases remain in milestone**
|
||||
**Route A: Phase verified, more phases remain**
|
||||
|
||||
```
|
||||
## ✓ Phase {Z}: {Name} Complete
|
||||
|
||||
All {Y} plans finished.
|
||||
All {Y} plans finished. Phase goal verified.
|
||||
|
||||
---
|
||||
|
||||
@@ -135,14 +134,14 @@ All {Y} plans finished.
|
||||
|
||||
---
|
||||
|
||||
**Route B: Milestone complete**
|
||||
**Route B: Phase verified, milestone complete**
|
||||
|
||||
```
|
||||
🎉 MILESTONE COMPLETE!
|
||||
|
||||
## ✓ Phase {Z}: {Name} Complete
|
||||
|
||||
All {N} phases finished.
|
||||
All {N} phases finished. All goals verified.
|
||||
|
||||
---
|
||||
|
||||
@@ -162,6 +161,46 @@ All {N} phases finished.
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Route C: Gaps found — need additional planning**
|
||||
|
||||
```
|
||||
## ⚠ Phase {Z}: {Name} — Gaps Found
|
||||
|
||||
**Score:** {N}/{M} must-haves verified
|
||||
**Report:** .planning/phases/{phase_dir}/{phase}-VERIFICATION.md
|
||||
|
||||
### What's Missing
|
||||
|
||||
{Extract gap summaries from VERIFICATION.md}
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Plan gap closure** — create additional plans to complete the phase
|
||||
|
||||
`/gsd:plan-phase {Z} --gaps`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md` — see full report
|
||||
- `/gsd:verify-work {Z}` — manual testing before planning
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
After user runs `/gsd:plan-phase {Z} --gaps`:
|
||||
1. Planner reads VERIFICATION.md gaps
|
||||
2. Creates plans 04, 05, etc. to close gaps
|
||||
3. User runs `/gsd:execute-phase {Z}` again
|
||||
4. Execute-phase runs incomplete plans (04, 05...)
|
||||
5. Verifier runs again → loop until passed
|
||||
</offer_next>
|
||||
|
||||
<wave_execution>
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: gsd:plan-phase
|
||||
description: Create detailed execution plan for a phase (PLAN.md)
|
||||
argument-hint: "[phase]"
|
||||
argument-hint: "[phase] [--gaps]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
@@ -18,6 +18,9 @@ Create executable phase prompt with discovery, context injection, and task break
|
||||
|
||||
Purpose: Break down roadmap phases into concrete, executable PLAN.md files that Claude can execute.
|
||||
Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-name/{phase}-{plan}-PLAN.md)
|
||||
|
||||
**Gap closure mode (`--gaps` flag):**
|
||||
When invoked with `--gaps`, plans address gaps identified by the verifier. Load VERIFICATION.md, create plans to close specific gaps.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@@ -33,6 +36,7 @@ Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-na
|
||||
|
||||
<context>
|
||||
Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided)
|
||||
Gap closure mode: `--gaps` flag triggers gap closure workflow
|
||||
|
||||
**Load project state first:**
|
||||
@.planning/STATE.md
|
||||
@@ -59,19 +63,33 @@ Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains rese
|
||||
|
||||
**Load codebase context if exists:**
|
||||
Check for `.planning/codebase/` and load relevant documents based on phase type.
|
||||
|
||||
**If --gaps flag present, also load:**
|
||||
@.planning/phases/XX-name/{phase}-VERIFICATION.md — contains structured gaps in YAML frontmatter
|
||||
</context>
|
||||
|
||||
<process>
|
||||
1. Check .planning/ directory exists (error if not - user should run /gsd:new-project)
|
||||
2. If phase number provided via $ARGUMENTS, validate it exists in roadmap
|
||||
3. If no phase number, detect next unplanned phase from roadmap
|
||||
4. Follow plan-phase.md workflow:
|
||||
2. Parse arguments: extract phase number and check for `--gaps` flag
|
||||
3. If phase number provided, validate it exists in roadmap
|
||||
4. If no phase number, detect next unplanned phase from roadmap
|
||||
|
||||
**Standard mode (no --gaps flag):**
|
||||
5. Follow plan-phase.md workflow:
|
||||
- Load project state and accumulated decisions
|
||||
- Perform mandatory discovery (Level 0-3 as appropriate)
|
||||
- Read project history (prior decisions, issues, concerns)
|
||||
- Break phase into tasks
|
||||
- Estimate scope and split into multiple plans if needed
|
||||
- Create PLAN.md file(s) with executable structure
|
||||
|
||||
**Gap closure mode (--gaps flag):**
|
||||
5. Follow plan-phase.md workflow with gap_closure_mode:
|
||||
- Load VERIFICATION.md and parse `gaps:` YAML from frontmatter
|
||||
- Read existing SUMMARYs to understand what's already built
|
||||
- Create tasks from gaps (each gap.missing item → task candidates)
|
||||
- Number plans sequentially after existing (if 01-03 exist, create 04, 05...)
|
||||
- Create PLAN.md file(s) focused on closing specific gaps
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
@@ -3,9 +3,7 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator s
|
||||
</purpose>
|
||||
|
||||
<core_principle>
|
||||
The orchestrator's job is coordination, not execution. Orchestrator discovers plans, groups into waves, spawns `gsd-executor` agents, handles checkpoints, collects results.
|
||||
|
||||
**Subagent:** `gsd-executor` — dedicated plan execution agent with all execution logic baked in.
|
||||
The orchestrator's job is coordination, not execution. Each subagent loads the full execute-plan context itself. Orchestrator discovers plans, analyzes dependencies, groups into waves, spawns agents, handles checkpoints, collects results.
|
||||
</core_principle>
|
||||
|
||||
<required_reading>
|
||||
@@ -152,34 +150,43 @@ Execute each wave in sequence. Autonomous plans within a wave run in parallel.
|
||||
- Bad: "Executing terrain generation plan"
|
||||
- Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
|
||||
|
||||
2. **Spawn all agents in wave simultaneously using gsd-executor:**
|
||||
2. **Spawn all autonomous agents in wave simultaneously:**
|
||||
|
||||
Use Task tool with multiple parallel calls. Each agent is `gsd-executor` with minimal prompt:
|
||||
Use Task tool with multiple parallel calls. Each agent gets prompt from subagent-task-prompt template:
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="Execute plan at {plan_path}
|
||||
<objective>
|
||||
Execute plan {plan_number} of phase {phase_number}-{phase_name}.
|
||||
|
||||
Plan: @{plan_path}
|
||||
Project state: @.planning/STATE.md
|
||||
Config: @.planning/config.json (if exists)",
|
||||
subagent_type="gsd-executor",
|
||||
description="Execute {phase}-{plan}"
|
||||
)
|
||||
Commit each task atomically. Create SUMMARY.md. Update STATE.md.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@~/.claude/get-shit-done/templates/summary.md
|
||||
@~/.claude/get-shit-done/references/checkpoints.md
|
||||
@~/.claude/get-shit-done/references/tdd.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Plan: @{plan_path}
|
||||
Project state: @.planning/STATE.md
|
||||
Config: @.planning/config.json (if exists)
|
||||
</context>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] All tasks executed
|
||||
- [ ] Each task committed individually
|
||||
- [ ] SUMMARY.md created in plan directory
|
||||
- [ ] STATE.md updated with position and decisions
|
||||
</success_criteria>
|
||||
```
|
||||
|
||||
The `gsd-executor` subagent has all execution logic baked in:
|
||||
- Deviation rules
|
||||
- Checkpoint protocols
|
||||
- Commit formatting
|
||||
- Summary creation
|
||||
- State updates
|
||||
|
||||
No template filling needed. Just pass the plan path.
|
||||
2. **Wait for all agents in wave to complete:**
|
||||
|
||||
Task tool blocks until each agent finishes. All parallel agents return together.
|
||||
|
||||
4. **Report completion and what was built:**
|
||||
3. **Report completion and what was built:**
|
||||
|
||||
For each completed agent:
|
||||
- Verify SUMMARY.md exists at expected path
|
||||
@@ -208,7 +215,7 @@ Config: @.planning/config.json (if exists)",
|
||||
- Bad: "Wave 2 complete. Proceeding to Wave 3."
|
||||
- Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
|
||||
|
||||
5. **Handle failures:**
|
||||
4. **Handle failures:**
|
||||
|
||||
If any agent in wave fails:
|
||||
- Report which plan failed and why
|
||||
@@ -216,11 +223,11 @@ Config: @.planning/config.json (if exists)",
|
||||
- If continue: proceed to next wave (dependent plans may also fail)
|
||||
- If stop: exit with partial completion report
|
||||
|
||||
6. **Execute checkpoint plans between waves:**
|
||||
5. **Execute checkpoint plans between waves:**
|
||||
|
||||
See `<checkpoint_handling>` for details.
|
||||
|
||||
7. **Proceed to next wave**
|
||||
6. **Proceed to next wave**
|
||||
|
||||
</step>
|
||||
|
||||
@@ -231,22 +238,15 @@ Plans with `autonomous: false` require user interaction.
|
||||
|
||||
**Execution flow for checkpoint plans:**
|
||||
|
||||
1. **Spawn gsd-executor for checkpoint plan:**
|
||||
1. **Spawn agent for checkpoint plan:**
|
||||
```
|
||||
Task(
|
||||
prompt="Execute plan at {plan_path}
|
||||
|
||||
Plan: @{plan_path}
|
||||
Project state: @.planning/STATE.md",
|
||||
subagent_type="gsd-executor",
|
||||
description="Execute {phase}-{plan}"
|
||||
)
|
||||
Task(prompt="{subagent-task-prompt}", subagent_type="general-purpose")
|
||||
```
|
||||
|
||||
2. **Agent runs until checkpoint:**
|
||||
- Executes auto tasks normally
|
||||
- Reaches checkpoint task or auth gate
|
||||
- Agent returns with structured checkpoint (format baked into gsd-executor)
|
||||
- Reaches checkpoint task (e.g., `type="checkpoint:human-verify"`) or auth gate
|
||||
- Agent returns with structured checkpoint (see checkpoint-return.md template)
|
||||
|
||||
3. **Agent return includes (structured format):**
|
||||
- Completed Tasks table with commit hashes and files
|
||||
@@ -275,29 +275,20 @@ Project state: @.planning/STATE.md",
|
||||
|
||||
6. **Spawn continuation agent (NOT resume):**
|
||||
|
||||
Spawn fresh `gsd-executor` with continuation context:
|
||||
Use the continuation-prompt.md template:
|
||||
```
|
||||
Task(
|
||||
prompt="Continue executing plan at {plan_path}
|
||||
|
||||
<completed_tasks>
|
||||
{completed_tasks_table from checkpoint return}
|
||||
</completed_tasks>
|
||||
|
||||
<resume_point>
|
||||
Resume from: Task {N} - {task_name}
|
||||
User response: {user_response}
|
||||
{resume_instructions based on checkpoint type}
|
||||
</resume_point>
|
||||
|
||||
Plan: @{plan_path}
|
||||
Project state: @.planning/STATE.md",
|
||||
subagent_type="gsd-executor",
|
||||
description="Continue {phase}-{plan}"
|
||||
prompt=filled_continuation_template,
|
||||
subagent_type="general-purpose"
|
||||
)
|
||||
```
|
||||
|
||||
The `gsd-executor` has continuation handling baked in — it will verify previous commits and resume correctly.
|
||||
Fill template with:
|
||||
- `{completed_tasks_table}`: From agent's checkpoint return
|
||||
- `{resume_task_number}`: Current task from checkpoint
|
||||
- `{resume_task_name}`: Current task name from checkpoint
|
||||
- `{user_response}`: What user provided
|
||||
- `{resume_instructions}`: Based on checkpoint type (see continuation-prompt.md)
|
||||
|
||||
7. **Continuation agent executes:**
|
||||
- Verifies previous commits exist
|
||||
@@ -351,150 +342,101 @@ After all waves complete, aggregate results:
|
||||
</step>
|
||||
|
||||
<step name="verify_phase_goal">
|
||||
**Verify the phase GOAL was achieved, not just that tasks completed.**
|
||||
Verify phase achieved its GOAL, not just completed its TASKS.
|
||||
|
||||
This step catches the common failure: tasks done but goal not met (stubs, placeholders, unwired code).
|
||||
|
||||
**1. Spawn gsd-verifier subagent:**
|
||||
**Spawn verifier:**
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="Verify phase {phase_number} goal achievement
|
||||
prompt="Verify phase {phase_number} goal achievement.
|
||||
|
||||
Phase: {phase_number} - {phase_name}
|
||||
Phase goal: {phase_goal_from_roadmap}
|
||||
Phase directory: @.planning/phases/{phase_dir}/
|
||||
Phase directory: {phase_dir}
|
||||
Phase goal: {goal from ROADMAP.md}
|
||||
|
||||
Project context:
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/REQUIREMENTS.md (if exists)",
|
||||
subagent_type="gsd-verifier",
|
||||
description="Verify phase {phase_number}"
|
||||
Check must_haves against actual codebase. Create VERIFICATION.md.
|
||||
Verify what actually exists in the code.",
|
||||
subagent_type="gsd-verifier"
|
||||
)
|
||||
```
|
||||
|
||||
The `gsd-verifier` subagent has all verification logic baked in:
|
||||
- Establishes must-haves (from frontmatter or derived)
|
||||
- Verifies observable truths against codebase
|
||||
- Checks artifacts exist and are substantive (not stubs)
|
||||
- Traces key links (wiring between components)
|
||||
- Scans for anti-patterns
|
||||
- Creates VERIFICATION.md report
|
||||
- Returns status to orchestrator
|
||||
|
||||
**2. Verification subagent returns** with status and report path.
|
||||
|
||||
**3. Handle verification result:**
|
||||
|
||||
**If status = "passed":**
|
||||
```
|
||||
## ✓ Phase Verification Passed
|
||||
|
||||
All {N} must-haves verified:
|
||||
- {truth 1} ✓
|
||||
- {truth 2} ✓
|
||||
- {truth 3} ✓
|
||||
|
||||
Phase goal achieved. Proceeding to update roadmap.
|
||||
```
|
||||
|
||||
Continue to update_roadmap step.
|
||||
|
||||
**If status = "gaps_found":**
|
||||
```
|
||||
## ⚠️ Phase Verification Found Gaps
|
||||
|
||||
{M} of {N} must-haves incomplete:
|
||||
|
||||
| Must-Have | Status | Issue |
|
||||
|-----------|--------|-------|
|
||||
| {truth 1} | ✓ VERIFIED | - |
|
||||
| {truth 2} | ✗ FAILED | API route returns placeholder |
|
||||
| {truth 3} | ✗ FAILED | Component not wired to API |
|
||||
|
||||
### Recommended Fix Plans
|
||||
|
||||
1. **{phase}-{next}-PLAN.md**: {description}
|
||||
2. **{phase}-{next+1}-PLAN.md**: {description}
|
||||
|
||||
Creating fix plans and executing...
|
||||
```
|
||||
|
||||
Then:
|
||||
1. Generate fix PLAN.md files from recommendations
|
||||
2. Execute fix plans (loop back to execute_waves)
|
||||
3. Re-verify (loop back to verify_phase_goal)
|
||||
4. Repeat until all must-haves pass
|
||||
|
||||
**If status = "human_needed":**
|
||||
```
|
||||
## 👤 Human Verification Required
|
||||
|
||||
Automated checks passed. These items need manual testing:
|
||||
|
||||
### 1. {Test Name}
|
||||
**Test:** {what to do}
|
||||
**Expected:** {what should happen}
|
||||
|
||||
### 2. {Test Name}
|
||||
**Test:** {what to do}
|
||||
**Expected:** {what should happen}
|
||||
|
||||
After testing, type "verified" or describe issues found.
|
||||
```
|
||||
|
||||
Wait for user response:
|
||||
- "verified" / "pass" / "ok" → Continue to update_roadmap
|
||||
- Description of issues → Generate fix plans, execute, re-verify
|
||||
|
||||
**4. Fix plan generation:**
|
||||
|
||||
When gaps are found, generate fix plans:
|
||||
**Read verification status:**
|
||||
|
||||
```bash
|
||||
# Create fix plan from verification recommendations
|
||||
NEXT_PLAN_NUM=$(ls "$PHASE_DIR"/*-PLAN.md | wc -l)
|
||||
NEXT_PLAN_NUM=$((NEXT_PLAN_NUM + 1))
|
||||
grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
|
||||
```
|
||||
|
||||
Fix plans:
|
||||
- Use standard PLAN.md template
|
||||
- Include must_haves (same as original, for re-verification)
|
||||
- Tasks target specific gaps (not entire feature)
|
||||
- Wave 99 (runs after all original plans)
|
||||
**Route by status:**
|
||||
|
||||
**5. Re-verification loop:**
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `passed` | Continue to update_roadmap |
|
||||
| `human_needed` | Present items to user, get approval or feedback |
|
||||
| `gaps_found` | Present gap summary, offer `/gsd:plan-phase {phase} --gaps` |
|
||||
|
||||
After fix plans execute:
|
||||
1. Spawn verification subagent again
|
||||
2. Check same must-haves
|
||||
3. If still gaps → more fix plans
|
||||
4. If passed → continue
|
||||
**If passed:**
|
||||
|
||||
Limit: 3 fix cycles. If still failing after 3 rounds, present to user:
|
||||
```
|
||||
## ⚠️ Verification Still Failing After 3 Fix Attempts
|
||||
Phase goal verified. Proceed to update_roadmap.
|
||||
|
||||
Remaining gaps:
|
||||
- {gap 1}
|
||||
- {gap 2}
|
||||
**If human_needed:**
|
||||
|
||||
Options:
|
||||
1. Continue anyway (manual fixes later)
|
||||
2. Stop and investigate
|
||||
```markdown
|
||||
## ✓ Phase {X}: {Name} — Human Verification Required
|
||||
|
||||
All automated checks passed. {N} items need human testing:
|
||||
|
||||
### Human Verification Checklist
|
||||
|
||||
{Extract from VERIFICATION.md human_verification section}
|
||||
|
||||
---
|
||||
|
||||
**After testing:**
|
||||
- "approved" → continue to update_roadmap
|
||||
- Report issues → will route to gap closure planning
|
||||
```
|
||||
|
||||
**Why this matters:**
|
||||
If user approves → continue to update_roadmap.
|
||||
If user reports issues → treat as gaps_found.
|
||||
|
||||
Without verification:
|
||||
- Phase 3 "complete" but chat doesn't work
|
||||
- Phase 4 builds on broken foundation
|
||||
- Phase 8: "nothing works, start over"
|
||||
**If gaps_found:**
|
||||
|
||||
With verification:
|
||||
- Phase 3 verified before moving on
|
||||
- Gaps caught and fixed immediately
|
||||
- Each phase delivers real value
|
||||
Present gaps and offer next command:
|
||||
|
||||
```markdown
|
||||
## ⚠ Phase {X}: {Name} — Gaps Found
|
||||
|
||||
**Score:** {N}/{M} must-haves verified
|
||||
**Report:** {phase_dir}/{phase}-VERIFICATION.md
|
||||
|
||||
### What's Missing
|
||||
|
||||
{Extract gap summaries from VERIFICATION.md gaps section}
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Plan gap closure** — create additional plans to complete the phase
|
||||
|
||||
`/gsd:plan-phase {X} --gaps`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `cat {phase_dir}/{phase}-VERIFICATION.md` — see full report
|
||||
- `/gsd:verify-work {X}` — manual testing before planning
|
||||
```
|
||||
|
||||
User runs `/gsd:plan-phase {X} --gaps` which:
|
||||
1. Reads VERIFICATION.md gaps
|
||||
2. Creates additional plans (04, 05, etc.) to close gaps
|
||||
3. User then runs `/gsd:execute-phase {X}` again
|
||||
4. Execute-phase runs incomplete plans (04-05)
|
||||
5. Verifier runs again after new plans complete
|
||||
|
||||
User stays in control at each decision point.
|
||||
</step>
|
||||
|
||||
<step name="update_roadmap">
|
||||
@@ -544,21 +486,20 @@ All {N} phases executed.
|
||||
|
||||
Orchestrator context usage: ~10-15%
|
||||
- Read plan frontmatter (small)
|
||||
- Group by wave (logic, no heavy reads)
|
||||
- Spawn Task calls with minimal prompts
|
||||
- Analyze dependencies (logic, no heavy reads)
|
||||
- Fill template strings
|
||||
- Spawn Task calls
|
||||
- Collect results
|
||||
|
||||
Each `gsd-executor` subagent: Fresh 200k context
|
||||
- Execution logic baked into subagent prompt (cached)
|
||||
- Only plan-specific context varies
|
||||
Each subagent: Fresh 200k context
|
||||
- Loads full execute-plan workflow
|
||||
- Loads templates, references
|
||||
- Executes plan with full capacity
|
||||
- Creates SUMMARY, commits
|
||||
|
||||
**Prompt caching benefit:** The `gsd-executor` subagent prompt is stable across all invocations. Only the plan path varies. 90% cost reduction on cached portion.
|
||||
|
||||
**No polling.** Task tool blocks until completion. No TaskOutput loops.
|
||||
|
||||
**No context bleed.** Orchestrator never reads execution internals. Just paths and results.
|
||||
**No context bleed.** Orchestrator never reads workflow internals. Just paths and results.
|
||||
</context_efficiency>
|
||||
|
||||
<failure_handling>
|
||||
|
||||
@@ -100,6 +100,114 @@ If multiple phases available, ask which one to plan. If obvious (first incomplet
|
||||
**If decimal phase:** Validate integer X exists and is complete, X+1 exists in roadmap, decimal X.Y doesn't exist, Y >= 1.
|
||||
|
||||
Read any existing PLAN.md or DISCOVERY.md in the phase directory.
|
||||
|
||||
**Check for --gaps flag:**
|
||||
If `--gaps` present in arguments, switch to gap_closure_mode (see `<step name="gap_closure_mode">`).
|
||||
</step>
|
||||
|
||||
<step name="gap_closure_mode">
|
||||
**Triggered by `--gaps` flag.** Plans address verification gaps.
|
||||
|
||||
**1. Load VERIFICATION.md:**
|
||||
|
||||
```bash
|
||||
PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1)
|
||||
cat "$PHASE_DIR"/*-VERIFICATION.md
|
||||
```
|
||||
|
||||
**2. Parse gaps from YAML frontmatter:**
|
||||
|
||||
Extract `gaps:` array. Each gap has:
|
||||
- `truth`: The observable behavior that failed
|
||||
- `reason`: Why it failed
|
||||
- `artifacts`: Files with issues
|
||||
- `missing`: Specific things to add/fix
|
||||
|
||||
**3. Load existing SUMMARYs:**
|
||||
|
||||
```bash
|
||||
ls "$PHASE_DIR"/*-SUMMARY.md
|
||||
```
|
||||
|
||||
Understand what's already built. Gap closure plans reference existing work.
|
||||
|
||||
**4. Find next plan number:**
|
||||
|
||||
```bash
|
||||
# Get highest existing plan number
|
||||
ls "$PHASE_DIR"/*-PLAN.md | sort -V | tail -1
|
||||
```
|
||||
|
||||
If plans 01, 02, 03 exist, next is 04.
|
||||
|
||||
**5. Group gaps into plans:**
|
||||
|
||||
Cluster related gaps by:
|
||||
- Same artifact (multiple issues in Chat.tsx → one plan)
|
||||
- Same concern (fetch + render → one "wire frontend" plan)
|
||||
- Dependency order (can't wire if artifact is stub → fix stub first)
|
||||
|
||||
**6. Create gap closure tasks:**
|
||||
|
||||
For each gap:
|
||||
```xml
|
||||
<task name="{fix_description}" type="auto">
|
||||
<files>{artifact.path}</files>
|
||||
<action>
|
||||
{For each item in gap.missing:}
|
||||
- {missing item}
|
||||
|
||||
Reference existing code: {from SUMMARYs}
|
||||
Gap reason: {gap.reason}
|
||||
</action>
|
||||
<verify>{How to confirm gap is closed}</verify>
|
||||
<done>{Observable truth now achievable}</done>
|
||||
</task>
|
||||
```
|
||||
|
||||
**7. Write PLAN.md files:**
|
||||
|
||||
Use standard template but note gap closure context:
|
||||
|
||||
```yaml
|
||||
---
|
||||
phase: XX-name
|
||||
plan: NN # Sequential after existing
|
||||
type: execute
|
||||
wave: 1 # Gap closures typically single wave
|
||||
depends_on: [] # Usually independent of each other
|
||||
files_modified: [...]
|
||||
autonomous: true
|
||||
gap_closure: true # Flag for tracking
|
||||
---
|
||||
```
|
||||
|
||||
**9. Present gap closure summary:**
|
||||
|
||||
```markdown
|
||||
## Gap Closure Plans Created
|
||||
|
||||
**Phase {X}: {Name}** — closing {N} gaps
|
||||
|
||||
| Plan | Gaps Addressed | Files |
|
||||
|------|----------------|-------|
|
||||
| {phase}-04 | {gap truths} | {files} |
|
||||
| {phase}-05 | {gap truths} | {files} |
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Execute gap closure plans**
|
||||
|
||||
`/gsd:execute-phase {X}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
**Skip directly to git_commit step after creating plans.**
|
||||
</step>
|
||||
|
||||
<step name="mandatory_discovery">
|
||||
@@ -240,120 +348,6 @@ cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null
|
||||
**If neither exist:** Suggest /gsd:research-phase for niche domains, /gsd:discuss-phase for simpler domains, or proceed with roadmap only.
|
||||
</step>
|
||||
|
||||
<step name="derive_must_haves">
|
||||
**BEFORE breaking into tasks, work BACKWARD from the phase goal.**
|
||||
|
||||
This step prevents the common failure mode: tasks complete but goal not achieved.
|
||||
|
||||
See `~/.claude/get-shit-done/references/goal-backward.md` for complete guidance.
|
||||
|
||||
**1. State the phase goal:**
|
||||
|
||||
Extract from ROADMAP.md. Reframe if task-shaped:
|
||||
- Task-shaped: "implement chat system" → Outcome-shaped: "users can chat"
|
||||
- Task-shaped: "add authentication" → Outcome-shaped: "users can log in securely"
|
||||
|
||||
**2. Derive observable truths:**
|
||||
|
||||
Ask: **"What must be TRUE for this goal to be achieved?"**
|
||||
|
||||
List 3-7 truths from the USER's perspective:
|
||||
- "User can see existing messages"
|
||||
- "User can type and send a message"
|
||||
- "Sent message appears in the list"
|
||||
- "Messages persist across refresh"
|
||||
|
||||
**Test:** Each truth should be verifiable by a human using the app. If you can't test it by clicking around, it's not observable.
|
||||
|
||||
**3. Derive required artifacts:**
|
||||
|
||||
For each truth, ask: **"What must EXIST for this to be true?"**
|
||||
|
||||
Map truths to concrete files:
|
||||
```
|
||||
"User can see existing messages" requires:
|
||||
- src/components/Chat.tsx (renders messages)
|
||||
- src/app/api/chat/route.ts (provides messages)
|
||||
- prisma/schema.prisma (Message model)
|
||||
```
|
||||
|
||||
**Test:** Each artifact should be a specific file path. If you can't point to where it lives, it's too abstract.
|
||||
|
||||
**4. Derive key links (wiring):**
|
||||
|
||||
For each artifact, ask: **"What must be CONNECTED for this to function?"**
|
||||
|
||||
Key links are critical connections:
|
||||
```
|
||||
- Chat.tsx → /api/chat: fetch in useEffect, response mapped to state
|
||||
- /api/chat GET → database: prisma.message.findMany, result returned
|
||||
- ChatInput onSubmit → /api/chat POST: fetch call, not just console.log
|
||||
```
|
||||
|
||||
**Test:** Wiring is verified by tracing data flow. Does A actually call B?
|
||||
|
||||
**5. Identify highest-risk links:**
|
||||
|
||||
Ask: **"Where is this most likely to break?"**
|
||||
|
||||
These get extra verification attention. Common high-risk links:
|
||||
- Form submit → API call (often stubbed with console.log)
|
||||
- API handler → database query (often returns hardcoded data)
|
||||
- Component → real data (often renders placeholder)
|
||||
|
||||
**6. Document must-haves:**
|
||||
|
||||
Structure for PLAN.md frontmatter:
|
||||
|
||||
```yaml
|
||||
must_haves:
|
||||
truths:
|
||||
- "User can see existing messages"
|
||||
- "User can send a message"
|
||||
- "Messages persist across refresh"
|
||||
artifacts:
|
||||
- path: "src/components/Chat.tsx"
|
||||
provides: "Message list rendering"
|
||||
min_lines: 30
|
||||
- path: "src/app/api/chat/route.ts"
|
||||
provides: "Message CRUD"
|
||||
exports: ["GET", "POST"]
|
||||
- path: "prisma/schema.prisma"
|
||||
provides: "Message model"
|
||||
contains: "model Message"
|
||||
key_links:
|
||||
- from: "src/components/Chat.tsx"
|
||||
to: "/api/chat"
|
||||
via: "fetch in useEffect"
|
||||
pattern: "fetch.*api/chat"
|
||||
- from: "src/app/api/chat/route.ts"
|
||||
to: "prisma.message"
|
||||
via: "database query"
|
||||
pattern: "prisma\\.message"
|
||||
```
|
||||
|
||||
**7. Use must-haves to inform task design:**
|
||||
|
||||
Tasks should CREATE artifacts and ESTABLISH key links. When writing tasks:
|
||||
- Each artifact should have a task that creates it
|
||||
- Each key link should be established (not left as TODO)
|
||||
- Verification should check the link works, not just that files exist
|
||||
|
||||
**Why this matters:**
|
||||
|
||||
Without goal-backward derivation, you get:
|
||||
- "Create Chat.tsx" ✓ (file exists, but renders placeholder)
|
||||
- "Create API route" ✓ (file exists, but returns hardcoded data)
|
||||
- "Phase complete" ✓ (all tasks done)
|
||||
- "App doesn't work" ✗ (goal not achieved)
|
||||
|
||||
With goal-backward derivation:
|
||||
- Must-haves define what "working" means
|
||||
- Tasks are designed to achieve must-haves
|
||||
- Verification checks must-haves after execution
|
||||
- Gaps found before they compound into later phases
|
||||
</step>
|
||||
|
||||
<step name="break_into_tasks">
|
||||
Decompose phase into tasks. **Think dependencies first, not sequence.**
|
||||
|
||||
@@ -843,23 +837,30 @@ Tasks are instructions for Claude, not Jira tickets.
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
Phase planning complete when:
|
||||
**Standard mode** — Phase planning complete when:
|
||||
- [ ] STATE.md read, project history absorbed
|
||||
- [ ] Mandatory discovery completed (Level 0-3)
|
||||
- [ ] Prior decisions, issues, concerns synthesized
|
||||
- [ ] **Must-haves derived** (truths, artifacts, key links from goal-backward analysis)
|
||||
- [ ] Dependency graph built (needs/creates for each task)
|
||||
- [ ] Tasks grouped into plans by wave, not by sequence
|
||||
- [ ] PLAN file(s) exist with XML structure
|
||||
- [ ] Each plan: depends_on, files_modified, autonomous in frontmatter
|
||||
- [ ] **Each plan: must_haves in frontmatter** (for post-execution verification)
|
||||
- [ ] Each plan: user_setup declared if external services involved
|
||||
- [ ] Each plan: Objective, context, tasks, verification, success criteria, output
|
||||
- [ ] Each plan: 2-3 tasks (~50% context)
|
||||
- [ ] Each task: Type, Files (if auto), Action, Verify, Done
|
||||
- [ ] **Tasks designed to CREATE artifacts and ESTABLISH key links**
|
||||
- [ ] Checkpoints properly structured
|
||||
- [ ] Wave structure maximizes parallelism
|
||||
- [ ] PLAN file(s) committed to git
|
||||
- [ ] User knows next steps and wave structure
|
||||
|
||||
**Gap closure mode (`--gaps`)** — Planning complete when:
|
||||
- [ ] VERIFICATION.md loaded and gaps parsed
|
||||
- [ ] Existing SUMMARYs read for context
|
||||
- [ ] Gaps clustered into focused plans
|
||||
- [ ] Plan numbers sequential after existing (04, 05...)
|
||||
- [ ] PLAN file(s) exist with gap_closure: true
|
||||
- [ ] Each plan: tasks derived from gap.missing items
|
||||
- [ ] PLAN file(s) committed to git
|
||||
- [ ] User knows to run `/gsd:execute-phase {X}` next
|
||||
</success_criteria>
|
||||
|
||||
Reference in New Issue
Block a user