diff --git a/agents/gsd-verifier.md b/agents/gsd-verifier.md index 07c8c043d..0821bd369 100644 --- 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 --- @@ -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
No messages
// Always shows "no messages" + - [ ] 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
No messages
// Always shows "no messages" - [ ] Fix plans generated (if gaps_found) - [ ] VERIFICATION.md created with complete report - [ ] Results returned to orchestrator (NOT committed) -
+