Evidence-based phase completion enforcement for /dev:feature. Use when orchestrating 8-phase feature development to ensure artifacts exist before phase completion, validation criteria are addressed, outer loops are enforced, and show-your-work requirements are met.
Evidence-based phase completion enforcement for /dev:feature. Use when orchestrating 8-phase feature development to ensure artifacts exist before phase completion, validation criteria are addressed, outer loops are enforced, and show-your-work requirements are met.
Before marking any phase complete:
1. Run checkpoint verification:
```bash
${PLUGIN_PATH}/scripts/checkpoint-verifier.sh phase{N} ${SESSION_PATH}
If check passes, mark task complete:
TaskUpdate(taskId: X, status: "completed")
If check fails, DO NOT mark complete. Fix missing artifacts first.
---
### 2. Outer Loop Enforcer
**Script:** `scripts/outer-loop-enforcer.js`
**How it works:**
- Tracks iteration state in session-meta.json
- Blocks Phase 8 unless Phase 7 PASSED
- Detects regression (score getting worse)
- Handles escalation when max iterations reached
**Commands:**
```bash
# Start new iteration (call before Phase 3)
node outer-loop-enforcer.js start-iteration ${SESSION_PATH}
# Record Phase 7 result
node outer-loop-enforcer.js record-result ${SESSION_PATH} PASS "All checks passed" 95
# Check if Phase 8 can proceed
node outer-loop-enforcer.js check-can-complete ${SESSION_PATH}
# Get current status
node outer-loop-enforcer.js get-status ${SESSION_PATH}
Session state tracking:
{"outerLoop":{"currentIteration":2,"maxIterations":3,"mode":"limited","phase7Results":[{"iteration":1,"status":"FAIL","reason":"Button color mismatch","score":78},{"iteration":2,"status":"PASS","reason":"All checks passed","score":94}]}}
### Show-Your-Work Requirement
**Anti-pattern (BLOCKED):**
```markdown
I'll run the tests now.
[Task tool call to run tests]
Tests passed! Moving to next phase.
Required pattern:
Running tests:
$ bun test
✓ auth.test.ts (5 tests)
✓ should authenticate valid user (12ms)
✓ should reject invalid password (8ms)
✓ should expire session after timeout (15ms)
✓ should refresh token correctly (10ms)
✓ should logout user (5ms)
✗ payment.test.ts (3 tests)
✓ should process valid payment (20ms)
✓ should reject invalid card (12ms)
✗ should handle timeout (FAILED)
Error: Expected timeout after 30s, got success
Results: 7 passed, 1 failed
The payment timeout test failure needs investigation before Phase 6 can complete.
Graceful Degradation
Three Completion Statuses
COMPLETE: All validation criteria passed
All artifacts created
All tests pass
Full validation executed
PARTIAL: Some validation done, gaps documented
Core functionality verified
Some criteria couldn't be tested (documented why)
Known limitations listed
INCOMPLETE: Blocked, needs user action
Critical blocker encountered
Cannot proceed without external input
Clear description of what's needed
Session Status in session-meta.json
{"status":"partial","completedCriteria":["builds","type-checks","login-flow"],"skippedCriteria":[{"criterion":"full-auth-flow","reason":"requires running server"},{"criterion":"token-storage","reason":"depends on auth flow"}],"blockers":[]}
Final Report for PARTIAL Status
## Feature Status: PARTIAL### Completed ✓- SDK implementation
- Type safety
- Build verification
### Not Verified ⚠️- End-to-end authentication (requires running server)
- Token storage persistence (depends on auth)
### Recommended Before Production1. Run integration tests with real server
2. Verify token encryption roundtrip
5. Failure Report Generator
Script:scripts/failure-report-generator.js
How it works:
Auto-generated when phase completion is blocked
Documents what was expected vs what happened
Lists all attempted approaches and their errors
Provides manual testing steps as fallback
Includes workarounds and suggestions
When generated:
Phase completion validator blocks a phase
Validation criteria enforcer finds gaps
Outer loop reaches max iterations
Any enforcement script fails
Report structure:
# {Phase Name} - Failure Report**Generated:** 2026-02-04T10:30:00Z
**Session:** ai-docs/sessions/dev-feature-login-20260204
**Phase:** phase7
## Expected Artifacts- ❌ `validation/result.md`- ❌ `validation/screenshot-before.png`- ❌ `validation/screenshot-after.png`## Attempted Approaches### Attempt 1: browser_test
**What was tried:** Chrome MCP navigation to localhost:3000
**Error:** Tool mcp__chrome-devtools__navigate_page not available**Timestamp:** 2026-02-04T10:25:00Z
## Failure Analysis### Common Failure Reasons-**chrome_mcp_unavailable**: Chrome MCP tools not available or not responding
-**server_not_starting**: Dev server fails to start
-**page_not_loading**: Test URL not accessible
## Suggestions for Resolution1. Verify Chrome MCP is properly configured in .claude/settings.json
2. Check if dev server is running: curl http://localhost:3000
3. Try using different browser automation: mcp__claude-in-chrome instead
4. Consider unit tests + manual verification as fallback
## Manual Testing Steps
1. Start dev server: npm run dev (or bun run dev)
2. Open browser to test URL (e.g., http://localhost:3000)
3. Take screenshot of initial state
4. Perform test actions (fill forms, click buttons)
5. Take screenshot of result state
6. Verify expected behavior occurred
7. Document results in validation/result.md
## Workarounds
### If Browser Automation Unavailable
1. Run validation manually in browser
2. Take screenshots with system screenshot tool
3. Save screenshots to `validation/` directory
4. Create `validation/result.md` with manual observations
### Minimal result.md Template
[template provided]
## Next Steps
1. **Fix and Retry**: Address the issues above and re-run the phase
2. **Manual Completion**: Follow manual steps and create artifacts manually
3. **Skip with Justification**: Create `phase7-skip-reason.md` explaining why
4. **Escalate to User**: Ask user for guidance via AskUserQuestion
Usage in orchestrator:
When phase completion is blocked:
1. Failure report auto-generated at:
${SESSION_PATH}/failures/phase{N}-failure-report.md
2. Read report and either:
a. Fix issues and retry
b. Follow manual testing steps
c. Create skip-reason.md with justification
d. Escalate to user with AskUserQuestion
3. If manually completing:
- Create required artifacts following templates in report
- Re-run phase completion validator
