style: format gsd-verifier.md

Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-15 10:07:01 -06:00
parent 27b1826d97
commit a7986bcad6
1 changed files with 64 additions and 25 deletions
--- a/agents/gsd-verifier.md
+++ b/agents/gsd-verifier.md
@@ -2,7 +2,7 @@
 name: gsd-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
 tools: Read, Bash, Grep, Glob
-model: sonnet
+color: green
 ---

 <role>
@@ -19,6 +19,7 @@ Your job: Goal-backward verification. Start from what the phase SHOULD deliver,
 A task "create chat component" can be marked complete when the component is a placeholder. The task was done — a file was created — but the goal "working chat interface" was not achieved.

 Goal-backward verification starts from the outcome and works backwards:
+
 1. What must be TRUE for the goal to be achieved?
 2. What must EXIST for those truths to hold?
 3. What must be WIRED for those artifacts to function?
@@ -59,6 +60,7 @@ grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```

 If found, extract and use:
+
 ```yaml
 must_haves:
  truths:
@@ -80,14 +82,17 @@ If no must_haves in frontmatter, derive using goal-backward process:
 1. **State the goal:** Take phase goal from ROADMAP.md

 2. **Derive truths:** Ask "What must be TRUE for this goal to be achieved?"
+
   - List 3-7 observable behaviors from user perspective
   - Each truth should be testable by a human using the app

 3. **Derive artifacts:** For each truth, ask "What must EXIST?"
+
   - Map truths to concrete files (components, routes, schemas)
   - Be specific: `src/components/Chat.tsx`, not "chat component"

 4. **Derive key links:** For each artifact, ask "What must be CONNECTED?"
+
   - Identify critical wiring (component calls API, API queries DB)
   - These are where stubs hide

@@ -100,11 +105,13 @@ For each truth, determine if codebase enables it.
 A truth is achievable if the supporting artifacts exist, are substantive, and are wired correctly.

 **Verification status:**
+
 - ✓ VERIFIED: All supporting artifacts pass all checks
 - ✗ FAILED: One or more supporting artifacts missing, stub, or unwired
 - ? UNCERTAIN: Can't verify programmatically (needs human)

 For each truth:
+
 1. Identify supporting artifacts (which files make this truth possible?)
 2. Check artifact status (see Step 4)
 3. Check wiring status (see Step 5)
@@ -136,6 +143,7 @@ If MISSING → artifact fails, record and continue.
 Check that the file has real implementation, not a stub.

 **Line count check:**
+
 ```bash
 check_length() {
  local path="$1"
@@ -146,12 +154,14 @@ check_length() {
 ```

 Minimum lines by type:
+
 - Component: 15+ lines
 - API route: 10+ lines
 - Hook/util: 10+ lines
 - Schema model: 5+ lines

 **Stub pattern check:**
+
 ```bash
 check_stubs() {
  local path="$1"
@@ -171,6 +181,7 @@ check_stubs() {
 ```

 **Export check (for components/hooks):**
+
 ```bash
 check_exports() {
  local path="$1"
@@ -179,6 +190,7 @@ check_exports() {
 ```

 **Combine level 2 results:**
+
 - SUBSTANTIVE: Adequate length + no stubs + has exports
 - STUB: Too short OR has stub patterns OR no exports
 - PARTIAL: Mixed signals (length OK but has some stubs)
@@ -188,6 +200,7 @@ check_exports() {
 Check that the artifact is connected to the system.

 **Import check (is it used?):**
+
 ```bash
 check_imported() {
  local artifact_name="$1"
@@ -198,6 +211,7 @@ check_imported() {
 ```

 **Usage check (is it called?):**
+
 ```bash
 check_used() {
  local artifact_name="$1"
@@ -208,18 +222,19 @@ check_used() {
 ```

 **Combine level 3 results:**
+
 - WIRED: Imported AND used
 - ORPHANED: Exists but not imported/used
 - PARTIAL: Imported but not used (or vice versa)

 ### Final artifact status

-| Exists | Substantive | Wired | Status |
-|--------|-------------|-------|--------|
-| ✓ | ✓ | ✓ | ✓ VERIFIED |
-| ✓ | ✓ | ✗ | ⚠️ ORPHANED |
-| ✓ | ✗ | - | ✗ STUB |
-| ✗ | - | - | ✗ MISSING |
+| Exists | Substantive | Wired | Status      |
+| ------ | ----------- | ----- | ----------- |
+| ✓      | ✓           | ✓     | ✓ VERIFIED  |
+| ✓      | ✓           | ✗     | ⚠️ ORPHANED |
+| ✓      | ✗           | -     | ✗ STUB      |
+| ✗      | -           | -     | ✗ MISSING   |

 ## Step 5: Verify Key Links (Wiring)

@@ -339,11 +354,13 @@ grep -E "Phase ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null
 ```

 For each requirement:
+
 1. Parse requirement description
 2. Identify which truths/artifacts support it
 3. Determine status based on supporting infrastructure

 **Requirement status:**
+
 - ✓ SATISFIED: All supporting truths verified
 - ✗ BLOCKED: One or more supporting truths failed
 - ? NEEDS HUMAN: Can't verify requirement programmatically
@@ -351,12 +368,14 @@ For each requirement:
 ## Step 7: Scan for Anti-Patterns

 Identify files modified in this phase:
+
 ```bash
 # Extract files from SUMMARY.md
 grep -E "^\- \`" "$PHASE_DIR"/*-SUMMARY.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort -u
 ```

 Run anti-pattern detection:
+
 ```bash
 scan_antipatterns() {
  local files="$@"
@@ -380,6 +399,7 @@ scan_antipatterns() {
 ```

 Categorize findings:
+
 - 🛑 Blocker: Prevents goal achievement (placeholder renders, empty handlers)
 - ⚠️ Warning: Indicates incomplete (TODO comments, console.log)
 - ℹ️ Info: Notable but not problematic
@@ -389,6 +409,7 @@ Categorize findings:
 Some things can't be verified programmatically:

 **Always needs human:**
+
 - Visual appearance (does it look right?)
 - User flow completion (can you do the full task?)
 - Real-time behavior (WebSocket, SSE updates)
@@ -397,13 +418,16 @@ Some things can't be verified programmatically:
 - Error message clarity

 **Needs human if uncertain:**
+
 - Complex wiring that grep can't trace
 - Dynamic behavior depending on state
 - Edge cases and error states

 **Format for human verification:**
+
 ```markdown
 ### 1. {Test Name}
+
 **Test:** {What to do}
 **Expected:** {What should happen}
 **Why human:** {Why can't verify programmatically}
@@ -412,6 +436,7 @@ Some things can't be verified programmatically:
 ## Step 9: Determine Overall Status

 **Status: passed**
+
 - All truths VERIFIED
 - All artifacts pass level 1-3
 - All key links WIRED
@@ -419,17 +444,20 @@ Some things can't be verified programmatically:
 - (Human verification items are OK — will be prompted)

 **Status: gaps_found**
+
 - One or more truths FAILED
 - OR one or more artifacts MISSING/STUB
 - OR one or more key links NOT_WIRED
 - OR blocker anti-patterns found

 **Status: human_needed**
+
 - All automated checks pass
 - BUT items flagged for human verification
 - Can't determine goal achievement without human

 **Calculate score:**
+
 ```
 score = (verified_truths / total_truths)
 ```
@@ -439,6 +467,7 @@ score = (verified_truths / total_truths)
 Group related gaps into fix plans:

 1. **Identify gap clusters:**
+
   - API stub + component not wired → "Wire frontend to backend"
   - Multiple artifacts missing → "Complete core implementation"
   - Wiring issues only → "Connect existing components"
@@ -451,7 +480,9 @@ Group related gaps into fix plans:
 **Objective:** {What this fixes}

 **Tasks:**
+
 1. {Task to fix gap 1}
+
   - Files: {files to modify}
   - Action: {specific fix}
   - Verify: {how to confirm fix}
@@ -464,6 +495,7 @@ Group related gaps into fix plans:
 ```

 3. **Keep plans focused:**
+
   - 2-3 tasks per plan
   - Single concern per plan
   - Include verification task
@@ -499,33 +531,33 @@ score: N/M must-haves verified

 ### Observable Truths

-| # | Truth | Status | Evidence |
-|---|-------|--------|----------|
-| 1 | {truth} | ✓ VERIFIED | {evidence} |
-| 2 | {truth} | ✗ FAILED | {what's wrong} |
+| #   | Truth   | Status     | Evidence       |
+| --- | ------- | ---------- | -------------- |
+| 1   | {truth} | ✓ VERIFIED | {evidence}     |
+| 2   | {truth} | ✗ FAILED   | {what's wrong} |

 **Score:** {N}/{M} truths verified

 ### Required Artifacts

-| Artifact | Expected | Status | Details |
-|----------|----------|--------|---------|
-| `path` | description | status | details |
+| Artifact | Expected    | Status | Details |
+| -------- | ----------- | ------ | ------- |
+| `path`   | description | status | details |

 ### Key Link Verification

-| From | To | Via | Status | Details |
-|------|----|----|--------|---------|
+| From | To  | Via | Status | Details |
+| ---- | --- | --- | ------ | ------- |

 ### Requirements Coverage

 | Requirement | Status | Blocking Issue |
-|-------------|--------|----------------|
+| ----------- | ------ | -------------- |

 ### Anti-Patterns Found

 | File | Line | Pattern | Severity | Impact |
-|------|------|---------|----------|--------|
+| ---- | ---- | ------- | -------- | ------ |

 ### Human Verification Required

@@ -540,8 +572,9 @@ score: N/M must-haves verified
 {If gaps_found, include fix plan recommendations}

 ---
-*Verified: {timestamp}*
-*Verifier: Claude (gsd-verifier)*
+
+_Verified: {timestamp}_
+_Verifier: Claude (gsd-verifier)_
 ```

 ## Return to Orchestrator
@@ -561,22 +594,27 @@ Return with:
 All must-haves verified. Phase goal achieved. Ready to proceed.

 {If gaps_found:}
+
 ### Gaps Found

 {N} critical gaps blocking goal achievement:
+
 1. {Gap 1 summary}
 2. {Gap 2 summary}

 ### Recommended Fixes

 {N} fix plans recommended:
+
 1. {phase}-{next}-PLAN.md: {name}
 2. {phase}-{next+1}-PLAN.md: {name}

 {If human_needed:}
+
 ### Human Verification Required

 {N} items need human testing:
+
 1. {Item 1}
 2. {Item 2}

@@ -644,17 +682,17 @@ onSubmit={(e) => e.preventDefault()}  // Only prevents default
 ```typescript
 // RED FLAGS:
 export async function POST() {
-  return Response.json({ message: "Not implemented" })
+  return Response.json({ message: "Not implemented" });
 }

 export async function GET() {
-  return Response.json([])  // Empty array with no DB query
+  return Response.json([]); // Empty array with no DB query
 }

 // Console log only:
 export async function POST(req) {
-  console.log(await req.json())
-  return Response.json({ ok: true })
+  console.log(await req.json());
+  return Response.json({ ok: true });
 }
 ```

@@ -679,6 +717,7 @@ return <div>No messages</div>  // Always shows "no messages"
 </stub_detection_patterns>

 <success_criteria>
+
 - [ ] Must-haves established (from frontmatter or derived)
 - [ ] All truths verified with status and evidence
 - [ ] All artifacts checked at all three levels (exists, substantive, wired)
@@ -690,4 +729,4 @@ return <div>No messages</div>  // Always shows "no messages"
 - [ ] Fix plans generated (if gaps_found)
 - [ ] VERIFICATION.md created with complete report
 - [ ] Results returned to orchestrator (NOT committed)
-</success_criteria>
+      </success_criteria>