Reality Verification
Core Rule
For fix goals: reproduce the failure BEFORE work, verify resolution AFTER.
Goal Detection
Classify user goals to determine if diagnosis is needed.
Detection Heuristics
| Pattern | Type | Match |
|---|---|---|
| fix, repair, resolve, debug, patch | Fix | \b(fix|repair|resolve|debug|patch)\b |
| broken, failing, error, bug, issue | Fix | \b(broken|failing|error|bug|issue)\b |
| "not working", "doesn't work" | Fix | not\s+working|doesn't\s+work |
| add, create, build, implement, new | Add | \b(add|create|build|implement|new)\b |
Conflict resolution: If both Fix and Add patterns present, treat as Fix. Fixing enables the feature.
Command Mapping
Map goal keywords to reproduction commands.
| Goal Keywords | Reproduction Command |
|---|---|
| CI, pipeline, actions | gh run view --log-failed |
| test, tests, spec | project test command (package.json scripts.test) |
| type, types, typescript | pnpm check-types or tsc --noEmit |
| lint, linting | pnpm lint or eslint . |
| build, compile | pnpm build or npm run build |
| deploy, deployment | gh api or MCP fetch to check status |
| E2E, UI, browser, visual | MCP playwright to screenshot or run E2E suite |
| endpoint, API, response | MCP fetch with expected status/response validation |
| site, page, live | MCP fetch/playwright to verify live behavior |
Fallback: If no keyword match, ask user or skip diagnosis.
E2E Verification with MCP Tools
For deployment and UI verification, use MCP tools:
Playwright (UI/E2E)
code
When goal involves: UI broken, E2E failing, visual regression, page not loading BEFORE: Use MCP playwright to: - Capture screenshot of broken state - Run failing E2E test - Document visible error AFTER: Same action should: - Show fixed UI - E2E test passes - No visible error
Fetch (API/Deployment)
code
When goal involves: API down, endpoint failing, deployment broken, 500 errors BEFORE: Use MCP fetch to: - Hit endpoint, capture status code - Document error response body - Note timestamp AFTER: Same endpoint should: - Return expected status (200, 201, etc) - Response matches expected schema - No error in body
BEFORE/AFTER Documentation
BEFORE State (Diagnosis)
Document in .progress.md under ## Reality Check (BEFORE):
markdown
## Reality Check (BEFORE) **Goal type**: Fix **Reproduction command**: `pnpm test` **Failure observed**: Yes **Output**:
FAIL src/auth.test.ts Expected: 200 Received: 401
code
**Timestamp**: 2026-01-16T10:30:00Z
AFTER State (Verification)
Document in .progress.md under ## Reality Check (AFTER):
markdown
## Reality Check (AFTER) **Command**: `pnpm test` **Result**: PASS **Output**:
PASS src/auth.test.ts All tests passed
code
**Comparison**: BEFORE failed with 401, AFTER passes **Verified**: Issue resolved
VF Task Format
Add as task 4.3 (after PR creation) for fix-type specs:
markdown
- [ ] 4.3 VF: Verify original issue resolved
- **Do**:
1. Read BEFORE state from .progress.md
2. Re-run reproduction command: `<command>`
3. Compare output with BEFORE state
4. Document AFTER state in .progress.md
- **Verify**: `grep -q "Verified: Issue resolved" ./specs/<name>/.progress.md`
- **Done when**: AFTER shows issue resolved, documented in .progress.md
- **Commit**: `chore(<name>): verify fix resolves original issue`
Why This Matters
| Without | With |
|---|---|
| "Fix CI" spec completes but CI still red | CI verified green before merge |
| Tests "fixed" but original failure unknown | Before/after comparison proves fix |
| Silent regressions | Explicit failure reproduction |
| Manual verification required | Automated verification in workflow |