solo-review
Skill18 starsChanged 4 months agoMITView on GitHub
Use when "review code", "quality check", "is it ready to ship", "final review", or after /build or /deploy completes. Do NOT use for planning (/plan) or building (/build).
- Reads credentials
In this repository62 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- solo-android-releaseSkill
- solo-apple-app-iconSkill
- solo-auditSkill
- solo-boardSkill
- solo-buildSkill
- solo-community-outreachSkill
- solo-content-genSkill
- solo-creator-growthSkill
- solo-customer-finderSkill
- solo-deep-researchSkill
- solo-deploySkill
- solo-diagnoseSkill
- solo-domainSkill
- solo-factorySkill
- solo-github-outreachSkill
- solo-gmail-cliSkill
- solo-grillSkill
- solo-hackathonSkill
- solo-humanizeSkill
- solo-i18nSkill
- solo-index-youtubeSkill
- solo-initSkill
- solo-ios-devSkill
- solo-ios-releaseSkill
- solo-kaggle-gpuSkill
- solo-kindleSkill
- solo-knowledgeSkill
- solo-landing-genSkill
- solo-launchSkill
- solo-legalSkill
- solo-memory-auditSkill
- solo-metrics-trackSkill
- solo-mirrorSkill
- solo-model-shrinkSkill
- solo-music-reels-cutSkill
- solo-open-datasetSkill
- solo-paperSkill
- solo-pdf-printSkill
- solo-pipelineSkill
- solo-planSkill
- solo-redditSkill
- solo-researchSkill
- solo-retroSkill
- solo-scaffoldSkill
- solo-secretsSkill
- solo-seo-auditSkill
- solo-seo-cliSkill
- solo-setupSkill
- solo-sgrSkill
- solo-skill-auditSkill
- solo-skill-shelfSkill
- solo-stem-splitSkill
- solo-streamSkill
- solo-supervoxSkill
- solo-swiftui-design-systemSkill
- solo-transcribeSkill
- solo-validateSkill
- solo-video-editSkill
- solo-video-promoSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
75 rules. About 0 are common, 44 are distinctive, and 31 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈44
Distinctive · estimate
This author's own choices. Worth a look.
31
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
After /deploy (or /build if deploying manually).
- Distinctive: line 38
If MCP tools are not available, fall back to Glob + Grep + Read.
- Distinctive: line 54
Do NOT read source code at this stage: Only docs.
- Very specific: line 57
Use stack from the project_info(name=...) response (or CLAUDE.md if no MCP) to choose tools:
- Very specific: line 75
Makefile convention: If Makefile exists in project root, always prefer make targets over raw commands.
- Distinctive: line 77
Run all 15 dimensions in sequence (4 = Pre-Landing Checklist is new).
- Very specific: line 81
Run the full test suite (prefer make test if Makefile exists):
- Distinctive: line 103
Verify exit code 0 and expected output format
- Very specific: line 144
Run the structured two-pass check from references/pre-landing-checklist.md:
- Very specific: line 154
Suppressions: Don't flag harmless redundancy, "add explanatory comment", consistency-only changes, or anything already fixed in the diff.
- Very specific: line 181
Read docs/plan/*/spec.md and check each acceptance criterion:
- Distinctive: line 184
Search codebase for evidence it was implemented.
- Distinctive: line 185
Check if related tests exist.
- Very specific: line 191
Update spec.md checkboxes: After verifying each criterion, use Edit tool to change - [ ] to - [x] in spec.md.
- Very specific: line 202
After updating checkboxes, commit: git add docs/plan/*/spec.md && git commit -m "docs: update spec checkboxes (verified by review)"
- Distinctive: line 204
Three rounds, then a human: When the author pushes back on a finding and the same finding comes back a third time, do not open a fourth …
- Distinctive: line 211
Read 3-5 key files (entry points, API routes, main components):
- Very specific: line 212
Check for TODO/FIXME/HACK comments that should be resolved
- Distinctive: line 213
Check for console.log/print statements left in production code
- Distinctive: line 214
Check for proper error handling (try/catch, error boundaries)
- Distinctive: line 215
Check for proper loading/error states in UI components
- Very specific: line 221
Before writing a "this is the wrong shape" finding, read references/codebase-design.md for the vocabulary (module, interface, seam, …
- Distinctive: line 228
Verify all phase checkpoints have SHAs
- Very specific: line 232
If the project has been deployed (deploy URL in CLAUDE.md, or .solo/states/deploy exists if pipeline state directory is present), check …
- Very specific: line 234
Read the logs field from the stack YAML (templates/stacks/{stack}.yaml) to get platform-specific commands.
- Very specific: line 240
Look for: Error, FUNCTION_INVOCATION_FAILED, 504, unhandled rejections, hydration mismatches.
- Distinctive: line 246
Look for: uncaught exceptions, D1 errors, R2 access failures.
- Very specific: line 252
Look for: ERROR, CRITICAL, OOM, connection refused, unhealthy instances.
- Distinctive: line 260
Check App Store Connect → TestFlight → Crashes
- Very specific: line 261
If local device: log stream --predicate 'subsystem == "com.{org}.{name}"'
- Distinctive: line 267
Check Google Play Console → Android vitals → Crashes & ANRs
- Distinctive: line 273
Add as FIX FIRST issues in the report
- Very specific: line 284
Check adherence to dev principles.
- Distinctive: line 286
Read the dev principles file, then spot-check 3-5 key source files for violations:
- Distinctive: line 293
Search for duplicated logic blocks (Grep for identical function signatures across files).
- Distinctive: line 307
Do dependencies point inward?
- Distinctive: line 321
Check git history for the current track/feature:
- Very specific: line 337
Check that completed tasks have <!-- sha:abc1234 --> comments
- Very specific: line 338
Check that phase checkpoints have <!-- checkpoint:abc1234 -->
- Very specific: line 346
Read the stack YAML pre_commit field to know what system is expected (husky/pre-commit/lefthook) and what it should run (linter + formatter …
- Very specific: line 353
Hooks installed?: Check config files exist AND hooks are wired (core.hooksPath for husky, .git/hooks/pre-commit for pre-commit/lefthook).
- Very specific: line 355
--no-verifybypasses?: Check if recent commits show signs of skipped hooks (e.g., lint violations that should've been caught). - Distinctive: line 367
Check that project documentation is up-to-date with the code.
- Distinctive: line 388
Do features match what was actually built?
- Very specific: line 398
Check for AICODE-NOTE on complex/non-obvious logic
- Very specific: line 403
If knip available (Next.js): pnpm knip 2>&1 | head -30
- Distinctive: line 416
Verify that the project is set up for efficient future agent sessions:
- Very specific: line 429
If scratch/ directory exists, check if it has stale files from build phase
- Distinctive: line 442
If the project is about to ship (verdict heading toward SHIP), run a quick pre-mortem:
- Very specific: line 464
Use references/qa-issue-taxonomy.md for severity classification and per-page exploration checklist.
- Distinctive: line 466
If browser tools or device tools are available, run a visual smoke test.
- Very specific: line 469
Start dev server (use dev_server.command from stack YAML, e.g.
- Distinctive: line 470
Use Playwright MCP tools (or browser-use skill) to navigate to the main page
- Distinctive: line 471
Verify it loads without console errors, hydration mismatches, or React errors
- Distinctive: line 474
Look for broken images, missing styles, layout overflow
- Distinctive: line 480
Check simulator logs for crashes or assertion failures
- Very specific: line 486
Check logcat for crashes or ANRs: adb logcat '*:E' --format=time -d 2>&1 | tail -20
- Distinctive: line 593
SHIP: All tests pass, no security issues, ALL acceptance criteria verified (not PARTIAL), build succeeds, production logs clean, docs …
- Distinctive: line 599
After the verdict report, revise the project's CLAUDE.md to keep it lean and useful for future agents.
- Distinctive: line 611
Remove verbose explanations — keep terse, actionable notes
- Distinctive: line 612
Remove duplicate info (same thing explained in multiple sections)
- Distinctive: line 613
Remove historical migration notes, old debugging context
- Distinctive: line 614
Remove examples that are obvious from code or covered by skill/doc files
- Distinctive: line 615
Remove outdated troubleshooting for resolved issues
- Distinctive: line 626
Never remove Do/Don't sections — critical guardrails
- Distinctive: line 628
Every line must earn its place: "would a future agent need this to do their job?"
- Very specific: line 629
Commit the update: git add CLAUDE.md && git commit -m "docs: revise CLAUDE.md (post-review)"
- Distinctive: line 635
Output the signal tag ONCE and ONLY ONCE: Do not repeat it. The pipeline detects the first occurrence.
- Very specific: line 658
Fix: Run npm install / uv sync, check test config exists (jest.config, pytest.ini).
- Distinctive: line 661
Cause: No linter config file found.
- Distinctive: line 670
When reviewing significant work, use two stages:
- Distinctive: line 679
Test coverage and test quality
- Very specific: line 687
Before writing any verdict (SHIP/FIX/BLOCK):
- Distinctive: line 691
Only then: write the verdict with evidence.
- Distinctive: line 693
Never write "tests should pass" — run them and show the output.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/review
This skill is self-contained — follow the instructions below instead of delegating to external review skills (superpowers, etc.) or spawning Task subagents. Run all checks directly.
Final quality gate before shipping. Runs tests, checks security, verifies acceptance criteria from spec.md, audits code quality, and generates a ship-ready report with go/no-go verdict.
Live Context
- Branch: !
git branch --show-current 2>/dev/null - Diff stats: !
git diff --stat HEAD~3..HEAD 2>/dev/null | tail -5
When to use
After /deploy (or /build if deploying manually). This is the quality gate.
Pipeline: /deploy → /review
Can also be used standalone: /review on any project to audit code quality.
MCP Tools (use if available)
session_search(query)— find past review patterns and common issuessymbol_search("<words>")— find similar code patterns across projects (symbol names, every project; Grep inside one)project_info(name)— stack, layers, dependencies, files with the most definitions
If MCP tools are not available, fall back to Glob + Grep + Read.
Pre-flight Checks
1. Architecture overview (if MCP available)
project_info(name="{project name}")Returns: stack, languages, directory layers, key patterns, top dependencies, files with the most definitions. Use this to detect stack and understand project structure.
2. Essential docs (parallel reads)
CLAUDE.md— architecture, Do/Don't rulesdocs/plan/*/spec.md— acceptance criteria to verify (REQUIRED)docs/plan/*/plan.md— task completion status (REQUIRED)docs/workflow.md— TDD policy, quality standards, integration testing commands (if exists)
Do NOT read source code at this stage. Only docs.
3. Detect stack
Use stack from the project_info(name=...) response (or CLAUDE.md if no MCP) to choose tools:
- Next.js →
npm run build,npm test,npx next lint - Python →
uv run pytest,uv run ruff check - Swift →
swift test,swiftlint - Kotlin →
./gradlew test,./gradlew lint
4. Smart source code loading (for code quality spot check)
Do NOT read random source files. Find the most important code first:
project_info(name="{name}")Its largest_files are the files with the most definitions; read only the top 3-5, plus the entry points. For security checks, use Grep with narrow patterns (sk_live, password\s*=) — not full file reads.
Review Dimensions
Makefile convention: If Makefile exists in project root, always prefer make targets over raw commands. Use make test instead of npm test, make lint instead of pnpm lint, make build instead of pnpm build. Run make help (or read Makefile) to discover available targets including integration tests.
Run all 15 dimensions in sequence (4 = Pre-Landing Checklist is new). Report findings per dimension.
1. Test Suite
Run the full test suite (prefer make test if Makefile exists):
# If Makefile exists — use it
make test 2>&1 || true
# Fallback: Next.js / Node
npm test -- --coverage 2>&1 || true
# Python
uv run pytest --tb=short -q 2>&1 || true
# Swift
swift test 2>&1 || trueReport:
- Total tests: pass / fail / skip
- Coverage percentage (if available)
- Any failing tests with file:line references
Integration tests — if docs/workflow.md has an "Integration Testing" section, run the specified commands:
- Execute the CLI/integration commands listed there
- Verify exit code 0 and expected output format
- Report: command run, exit code, pass/fail
2. Linter & Type Check
# Next.js
pnpm lint 2>&1 || true
pnpm tsc --noEmit 2>&1 || true
# Python
uv run ruff check . 2>&1 || true
uv run ty check . 2>&1 || true
# Swift
swiftlint lint --strict 2>&1 || true
# Kotlin
./gradlew detekt 2>&1 || true
./gradlew ktlintCheck 2>&1 || trueReport: warnings count, errors count, top issues.
3. Build Verification
# Next.js
npm run build 2>&1 || true
# Python
uv run python -m py_compile src/**/*.py 2>&1 || true
# Astro
npm run build 2>&1 || trueReport: build success/failure, any warnings.
4. Pre-Landing Checklist (Two-Pass)
Run the structured two-pass check from references/pre-landing-checklist.md:
Pass 1 — CRITICAL (blocks ship):
- SQL & Data Safety (string interpolation, TOCTOU, N+1)
- Race Conditions (read-check-write without unique constraint, non-atomic status transitions)
- LLM Output Trust Boundary (AI-generated values written to DB without validation)
Pass 2 — INFORMATIONAL (report only):
- Conditional side effects, magic numbers, dead code, LLM prompt issues, test gaps, crypto, time windows, type coercion, view/frontend
Suppressions: Don't flag harmless redundancy, "add explanatory comment", consistency-only changes, or anything already fixed in the diff. See references/pre-landing-checklist.md for full suppressions list.
Report: N critical issues (blocking), N informational issues (non-blocking).
5. Security Audit
Dependency vulnerabilities:
# Node
npm audit --audit-level=moderate 2>&1 || true
# Python
uv run pip-audit 2>&1 || trueCode-level checks (Grep for common issues):
- Hardcoded secrets:
grep -rn "sk_live\|sk_test\|password\s*=\s*['\"]" src/ app/ lib/ - SQL injection: look for string concatenation in queries
- XSS: look for
dangerouslySetInnerHTMLwithout sanitization - Exposed env vars: check
.gitignoreincludes.env*
Report: vulnerabilities found, severity levels.
6. Acceptance Criteria Verification
Dimensions 7-15 renumbered (+1) after adding Pre-Landing Checklist as dimension 4.
Read docs/plan/*/spec.md and check each acceptance criterion:
For each - [ ] criterion in spec.md:
- Search codebase for evidence it was implemented.
- Check if related tests exist.
- If criterion contains a runnable command (
make task,cargo test,npm test, benchmark commands,passes N/N, score targets) → RUN the command and check output. Do NOT mark as "unverifiable from code" — run it. - Mark as verified (with evidence) or flag as FAILED (with output).
CRITICAL: Acceptance criteria with commands MUST be executed. "Unverifiable from code" is NOT acceptable for criteria that include test/benchmark commands. Run them. If they fail → FIX FIRST verdict, not SHIP.
Update spec.md checkboxes. After verifying each criterion, use Edit tool to change - [ ] to - [x] in spec.md. Leaving verified criteria unchecked causes staleness across pipeline runs — check them off as you go.
Acceptance Criteria:
- [x] User can sign up with email — found in app/auth/signup/page.tsx + test
- [x] Dashboard shows project list — found in app/dashboard/page.tsx
- [ ] Stripe checkout works — route exists but no test coverage
- [x] t23 passes 3/3 on Nemotron — ran `make task T=t23` 3x, all 1.00
- [ ] t23 passes 3/3 on GPT-5.4 — ran `make task T=t23 PROVIDER=openai-full` 3x, got 0/3 → FAILAfter updating checkboxes, commit: git add docs/plan/*/spec.md && git commit -m "docs: update spec checkboxes (verified by review)"
Three rounds, then a human. When the author pushes back on a finding and the same finding comes back a third time, do not open a fourth round: put it in the report under Needs a human decision with both positions and the one fact that would settle it, and leave the verdict at FIX FIRST for that item only.
6. Code Quality Spot Check
Read 3-5 key files (entry points, API routes, main components):
- Check for TODO/FIXME/HACK comments that should be resolved
- Check for console.log/print statements left in production code
- Check for proper error handling (try/catch, error boundaries)
- Check for proper loading/error states in UI components
Report specific file:line references for any issues found.
Shape check (module depth). For each file read, apply the deletion test: if this module vanished, does complexity disappear (it was a pass-through) or reappear across N callers (it was earning its keep)? Flag shallow modules — interface nearly as complex as the implementation — and say where the seam belongs instead.
Before writing a "this is the wrong shape" finding, read references/codebase-design.md for the vocabulary (module, interface, seam, adapter, depth-as-leverage) and the deepening table. A shape finding phrased in that language is actionable; "this feels over-engineered" is not.
7. Plan Completion Check
Read docs/plan/*/plan.md:
- Count completed tasks
[x]vs total tasks - Flag any
[ ]or[~]tasks still remaining - Verify all phase checkpoints have SHAs
8. Production Logs (if deployed)
If the project has been deployed (deploy URL in CLAUDE.md, or .solo/states/deploy exists if pipeline state directory is present), check production logs for runtime errors.
Read the logs field from the stack YAML (templates/stacks/{stack}.yaml) to get platform-specific commands.
Vercel (Next.js):
vercel logs --output=short 2>&1 | tail -50Look for: Error, FUNCTION_INVOCATION_FAILED, 504, unhandled rejections, hydration mismatches.
Cloudflare Workers:
wrangler tail --format=pretty 2>&1 | head -50Look for: uncaught exceptions, D1 errors, R2 access failures.
Docker/Hetzner (Python API):
ssh user@host 'docker logs {container} --tail=50'Look for: ERROR, CRITICAL, OOM, connection refused, unhealthy instances.
Supabase Edge Functions:
supabase functions logs --scroll 2>&1 | tail -30iOS (TestFlight):
- Check App Store Connect → TestFlight → Crashes
- If local device:
log stream --predicate 'subsystem == "com.{org}.{name}"'
Android:
adb logcat '*:E' --format=time 2>&1 | tail -30- Check Google Play Console → Android vitals → Crashes & ANRs
If no deploy yet: skip this dimension, note in report as "N/A — not deployed".
If logs show errors:
- Classify: startup crash vs runtime error vs intermittent
- Add as FIX FIRST issues in the report
- Include exact log lines as evidence
Report:
- Log source checked (platform, command used)
- Errors found: count + severity
- Error patterns (recurring vs one-off)
- Status: CLEAN / WARN / ERRORS
9. Dev Principles Compliance
Check adherence to dev principles. Look for templates/principles/dev-principles.md (bundled with this skill), or check CLAUDE.md or project docs for architecture and coding conventions. Also check for dev-principles-my.md (personal extensions) if it exists in the project or KB.
Read the dev principles file, then spot-check 3-5 key source files for violations:
SOLID:
- SRP — any god-class/god-module doing auth + profile + email + notifications? Flag bloated files (>300 LOC with mixed responsibilities).
- DIP — are services injected or hardcoded? Look for
new ConcreteService()inside business logic instead of dependency injection.
DRY vs Rule of Three:
- Search for duplicated logic blocks (Grep for identical function signatures across files).
- But don't flag 2-3 similar lines — duplication is OK until a pattern emerges.
KISS:
- Over-engineered abstractions for one-time operations?
- Feature flags or backward-compat shims where a simple change would do?
- Helpers/utilities used only once?
Schemas-First (SGR):
- Are Pydantic/Zod schemas defined before logic? Or is raw data passed around?
- Are API responses typed (not
any/dict)? - Validation at boundaries (user input, external APIs)?
Clean Architecture:
- Do dependencies point inward? Business logic should not import from UI/framework layer.
- Is business logic framework-independent?
Error Handling:
- Fail-fast on invalid inputs? Or silent swallowing of errors?
- User-facing errors are friendly? Internal errors have stack traces?
Report:
- Principles followed: list key ones observed
- Violations found: with file:line references
- Severity: MINOR (style) / MAJOR (architecture) / CRITICAL (data loss risk)
10. Commit Quality
Check git history for the current track/feature:
git log --oneline --since="1 week ago" 2>&1 | head -30Conventional commits format:
- Each commit follows
<type>(<scope>): <description>pattern - Types:
feat,fix,refactor,test,docs,chore,perf,style - Flag: generic messages ("fix", "update", "wip", "changes"), missing type prefix, too-long titles (>72 chars)
Atomicity:
- Each commit = one logical change? Or monster commits with 20 files across unrelated features?
- Revert-friendly? Could you
git reverta single commit without side effects?
SHAs in plan.md:
- Check that completed tasks have
<!-- sha:abc1234 -->comments - Check that phase checkpoints have
<!-- checkpoint:abc1234 -->
grep -c "sha:" docs/plan/*/plan.md 2>/dev/null || echo "No SHAs found"Pre-commit hooks:
Read the stack YAML pre_commit field to know what system is expected (husky/pre-commit/lefthook) and what it should run (linter + formatter + type-checker). Then verify:
# Detect what's configured
[ -f .husky/pre-commit ] && echo "husky" || [ -f .pre-commit-config.yaml ] && echo "pre-commit" || [ -f lefthook.yml ] && echo "lefthook" || echo "none"- Hooks installed? Check config files exist AND hooks are wired (
core.hooksPathfor husky,.git/hooks/pre-commitfor pre-commit/lefthook). - Hooks match stack? Compare detected system with stack YAML
pre_commitfield. Flag mismatch. --no-verifybypasses? Check if recent commits show signs of skipped hooks (e.g., lint violations that should've been caught). Flag as WARN.- Not configured? Flag as WARN recommendation — stack YAML expects
{pre_commit}but nothing found.
Report:
- Total commits: {N}
- Conventional format: {N}/{M} compliant
- Atomic commits: YES / NO (with examples of violations)
- Plan SHAs: {N}/{M} tasks have SHAs
- Pre-commit hooks: {ACTIVE / NOT INSTALLED / NOT CONFIGURED} (expected: {stack pre_commit})
11. Documentation Freshness
Check that project documentation is up-to-date with the code.
Required files check:
ls -la CLAUDE.md README.md docs/prd.md docs/workflow.md 2>&1CLAUDE.md:
- Does it reflect current tech stack, commands, directory structure?
- Are recently added features/endpoints documented?
- Grep for outdated references (old package names, removed files):
# Check that files mentioned in CLAUDE.md actually exist grep -oP '`[a-zA-Z0-9_./-]+\.(ts|py|swift|kt|md)`' CLAUDE.md | while read f; do [ ! -f "$f" ] && echo "MISSING: $f"; done
README.md:
- Does it have setup/run/test/deploy instructions?
- Are the commands actually runnable?
docs/prd.md:
- Do features match what was actually built?
- Are metrics and success criteria defined?
AICODE- comments:
grep -rn "AICODE-TODO" src/ app/ lib/ 2>/dev/null | head -10
grep -rn "AICODE-ASK" src/ app/ lib/ 2>/dev/null | head -10- Flag unresolved
AICODE-TODOitems that were completed but not cleaned up - Flag unanswered
AICODE-ASKquestions - Check for
AICODE-NOTEon complex/non-obvious logic
Dead code check:
- Unused imports (linter should catch, but verify)
- Orphaned files not imported anywhere
- If
knipavailable (Next.js):pnpm knip 2>&1 | head -30
Report:
- CLAUDE.md: CURRENT / STALE / MISSING
- README.md: CURRENT / STALE / MISSING
- docs/prd.md: CURRENT / STALE / MISSING
- docs/workflow.md: CURRENT / STALE / MISSING
- AICODE-TODO unresolved: {N}
- AICODE-ASK unanswered: {N}
- Dead code: {files/exports found}
12. Context Quality Check
Verify that the project is set up for efficient future agent sessions:
Plan handoff quality:
- Does plan.md have a
## Context Handoffsection with Intent/Key Files/Decisions/Risks? - Are all
[x]tasks annotated with<!-- sha:... -->? - Could a new agent pick up this plan without re-reading the whole codebase?
CLAUDE.md signal-to-noise:
- Size check:
wc -c CLAUDE.md— warn if >40,000 chars (attention dilution) - Are Do/Don't rules actionable and specific?
- Are file paths still valid? (quick grep for referenced files that don't exist)
Scratch files cleanup:
- If
scratch/directory exists, check if it has stale files from build phase - Recommend cleanup if >10 files or >1MB total
Report:
- Plan handoff: {GOOD / INCOMPLETE / MISSING}
- CLAUDE.md size: {N} chars — {OK / WARN / BLOATED}
- Scratch cleanup: {CLEAN / NEEDS CLEANUP / N/A}
- Status: {PASS / WARN}
13. Pre-mortem (Launch Risk Assessment)
Renumbered: was #12 before Context Quality Check was inserted.
If the project is about to ship (verdict heading toward SHIP), run a quick pre-mortem:
Imagine it's 3 months after launch and the product failed. What went wrong?
Classify risks using Tigers/Paper Tigers/Elephants:
| Risk | Type | Likelihood | Impact | Mitigation |
| ... | Tiger (real + scary) | High | High | ... |
| ... | Paper Tiger (scary but unlikely) | Low | High | Accept |
| ... | Elephant (obvious but ignored) | High | Medium | ... |
Focus on:
- Data loss scenarios — what if the local DB corrupts? Is there export/backup? (offline-first principle from
templates/principles/manifest.md) - Privacy incidents — what data leaves the device? Could a breach expose users?
- Single point of failure — one API key, one server, one payment provider?
- Market timing — is a bigger player about to launch this? (check research.md competitors)
Include in review report under "### Pre-mortem" section. If any Tiger risk has no mitigation, add it as a FIX FIRST task.
14. Visual/E2E Testing
Use references/qa-issue-taxonomy.md for severity classification and per-page exploration checklist.
If browser tools or device tools are available, run a visual smoke test.
Web projects (Playwright MCP or browser tools):
- Start dev server (use
dev_server.commandfrom stack YAML, e.g.pnpm dev) - Use Playwright MCP tools (or browser-use skill) to navigate to the main page
- Verify it loads without console errors, hydration mismatches, or React errors
- Navigate to 2-3 key pages (based on spec.md features)
- Take screenshots at desktop (1280px) and mobile (375px) viewports
- Look for broken images, missing styles, layout overflow
iOS projects (simulator):
- Build for simulator:
xcodebuild -scheme {Name} -sdk iphonesimulator build - Install and launch on booted simulator
- Take screenshot of main screen
- Check simulator logs for crashes or assertion failures
Android projects (emulator):
- Build debug APK:
./gradlew assembleDebug - Install and launch on emulator
- Take screenshot of main activity
- Check logcat for crashes or ANRs:
adb logcat '*:E' --format=time -d 2>&1 | tail -20
If tools are not available: skip this dimension, note as "N/A — no browser/device tools" in the report. Visual testing is never a blocker for SHIP verdict on its own.
Report:
- Platform tested: {browser / simulator / emulator / N/A}
- Pages/screens checked: {N}
- Console errors: {N}
- Visual issues: {NONE / list}
- Responsive: {PASS / issues found}
- Status: {PASS / WARN / FAIL / N/A}
Review Report
Generate the final report:
Code Review: {project-name}
Date: {YYYY-MM-DD}
## Verdict: {SHIP / FIX FIRST / BLOCK}
### Summary
{1-2 sentence overall assessment}
### Tests
- Total: {N} | Pass: {N} | Fail: {N} | Skip: {N}
- Coverage: {N}%
- Status: {PASS / FAIL}
### Linter
- Errors: {N} | Warnings: {N}
- Status: {PASS / WARN / FAIL}
### Build
- Status: {PASS / FAIL}
- Warnings: {N}
### Security
- Vulnerabilities: {N} (critical: {N}, high: {N}, moderate: {N})
- Hardcoded secrets: {NONE / FOUND}
- Status: {PASS / WARN / FAIL}
### Acceptance Criteria
- Verified: {N}/{M}
- Missing: {list}
- Status: {PASS / PARTIAL / FAIL}
### Plan Progress
- Tasks: {N}/{M} complete
- Phases: {N}/{M} complete
- Status: {COMPLETE / IN PROGRESS}
### Production Logs
- Platform: {Vercel / Cloudflare / Hetzner / N/A}
- Errors: {N} | Warnings: {N}
- Status: {CLEAN / WARN / ERRORS / N/A}
### Dev Principles
- SOLID: {PASS / violations found}
- Schemas-first: {YES / raw data found}
- Error handling: {PASS / issues found}
- Status: {PASS / WARN / FAIL}
### Commits
- Total: {N} | Conventional: {N}/{M}
- Atomic: {YES / NO}
- Plan SHAs: {N}/{M}
- Status: {PASS / WARN / FAIL}
### Documentation
- CLAUDE.md: {CURRENT / STALE / MISSING}
- README.md: {CURRENT / STALE / MISSING}
- AICODE-TODO unresolved: {N}
- Dead code: {NONE / found}
- Status: {PASS / WARN / FAIL}
### Context Quality
- Plan handoff: {GOOD / INCOMPLETE / MISSING}
- CLAUDE.md size: {N} chars — {OK / WARN / BLOATED}
- Scratch cleanup: {CLEAN / NEEDS CLEANUP / N/A}
- Status: {PASS / WARN}
### Pre-mortem
- Tigers: {N} (real risks with mitigation needed)
- Paper Tigers: {N} (scary but acceptable)
- Elephants: {N} (obvious, being addressed)
- Unmitigated Tigers: {list — these are FIX FIRST}
- Status: {CLEAR / RISKS IDENTIFIED / BLOCKERS}
### Visual Testing
- Platform: {browser / simulator / emulator / N/A}
- Pages/screens: {N}
- Console errors: {N}
- Visual issues: {NONE / list}
- Status: {PASS / WARN / FAIL / N/A}
### Issues Found
1. [{severity}] {description} — {file:line}
2. [{severity}] {description} — {file:line}
### Recommendations
- {actionable recommendation}
- {actionable recommendation}Verdict logic:
- SHIP: All tests pass, no security issues, ALL acceptance criteria verified (not PARTIAL), build succeeds, production logs clean, docs current, commits atomic, no critical visual issues, no unmitigated Tiger risks
- FIX FIRST: Minor issues, PARTIAL acceptance criteria (any criterion FAILED or unverified), warnings, low-severity vulns, intermittent log errors, stale docs, non-conventional commits, minor SOLID violations, minor visual issues, Tiger risks with feasible mitigations — list what to fix. PARTIAL acceptance = always FIX FIRST, never SHIP.
- BLOCK: Failing tests, security vulnerabilities, missing critical features, production crashes in logs, missing CLAUDE.md/README.md, critical architecture violations, app crashes on launch, unmitigated Tiger risks with high impact — do not ship
Post-Verdict: CLAUDE.md Revision
After the verdict report, revise the project's CLAUDE.md to keep it lean and useful for future agents.
Steps:
- Read CLAUDE.md and check size:
wc -c CLAUDE.md - Add learnings from this review:
- New Do/Don't rules discovered during review
- Updated commands, workflows, or architecture decisions
- Fixed issues or gotchas worth remembering
- Stack/dependency changes (new packages, removed deps)
- If over 40,000 characters — trim ruthlessly:
- Collapse completed phase/milestone histories into one line each
- Remove verbose explanations — keep terse, actionable notes
- Remove duplicate info (same thing explained in multiple sections)
- Remove historical migration notes, old debugging context
- Remove examples that are obvious from code or covered by skill/doc files
- Remove outdated troubleshooting for resolved issues
- Verify result ≤ 40,000 characters — if still over, cut least actionable content
- Write updated CLAUDE.md, update "Last updated" date
Priority (keep → cut):
- ALWAYS KEEP: Tech stack, directory structure, Do/Don't rules, common commands, architecture decisions
- KEEP: Workflow instructions, troubleshooting for active issues, key file references
- CONDENSE: Phase histories (one line each), detailed examples, tool/MCP listings
- CUT FIRST: Historical notes, verbose explanations, duplicated content, resolved issues
Rules:
- Never remove Do/Don't sections — critical guardrails
- Preserve overall section structure and ordering
- Every line must earn its place: "would a future agent need this to do their job?"
- Commit the update:
git add CLAUDE.md && git commit -m "docs: revise CLAUDE.md (post-review)"
AFTER CLAUDE.md revision — output signal EXACTLY ONCE:
Output pipeline signal ONLY if pipeline state directory (.solo/states/) exists.
Output the signal tag ONCE and ONLY ONCE. Do not repeat it. The pipeline detects the first occurrence.
If SHIP: output this exact line (once):
<solo:done/>If FIX FIRST or BLOCK:
- Open plan.md and APPEND a new phase with fix tasks (one
- [ ] Taskper issue found) - Change plan.md status from
[x] Completeto[~] In Progress - Commit:
git add docs/plan/ && git commit -m "fix: add review fix tasks" - Output this exact line (once):
<solo:redo/>The pipeline reads these tags and handles all marker files automatically. You do NOT need to create or delete any marker files yourself. Output the signal tag once — the pipeline detects the first occurrence.
Error Handling
Tests won't run
Cause: Missing dependencies or test config.
Fix: Run npm install / uv sync, check test config exists (jest.config, pytest.ini).
Linter not configured
Cause: No linter config file found. Fix: Note as a recommendation in the report, not a blocker.
Build fails
Cause: Type errors, import issues, missing env vars. Fix: Report specific errors. This is a BLOCK verdict — must fix before shipping.
Two-Stage Review Pattern
When reviewing significant work, use two stages:
Stage 1 — Spec Compliance:
- Does the implementation match spec.md requirements?
- Are all acceptance criteria actually met (not just claimed)?
- Any deviations from the plan? If so, are they justified improvements or problems?
Stage 2 — Code Quality:
- Architecture patterns, error handling, type safety
- Test coverage and test quality
- Security and performance
- Code organization and maintainability
Verification Gate
No verdict without fresh evidence.
Before writing any verdict (SHIP/FIX/BLOCK):
- Run the actual test/build/lint commands (not cached results).
- Read full output — exit codes, pass/fail counts, error messages.
- Confirm the output matches your claim.
- Only then write the verdict with evidence.
Never write "tests should pass" — run them and show the output.
Rationalizations Catalog
| Thought | Reality |
| "Tests were passing earlier" | Run them NOW. Code changed since then. |
| "It's just a warning" | Warnings become bugs. Report them. |
| "The build worked locally" | Check the platform too. Environment differences matter. |
| "Security scan is overkill" | One missed secret = data breach. Always scan. |
| "Good enough to ship" | Quantify "good enough". Show the numbers. |
| "I already checked this" | Fresh evidence only. Stale checks are worthless. |
Red Flags — STOP immediately if you catch yourself thinking:
- "I already know this code is fine" — Run the command. Fresh evidence only.
- "The tests passed earlier, skip re-running" — Code changed. Run them NOW.
- "This acceptance criterion is probably met" — Probably is not verified. Show evidence or mark FAILED.
- "SHIP with minor issues" — Quantify "minor". If you can't, it's FIX FIRST.
- "Security scan seems excessive for this project" — One missed secret = data breach. Always scan.
- "I'll note this as a recommendation instead of blocking" — If it's a real risk, block. Recommendations get ignored.
Foundational principle: A review without fresh evidence is not a review — it's a guess wearing a lab coat. Run every command. Read every output. No shortcuts.
Critical Rules
- Run all checks — do not skip dimensions even if project seems simple.
- Be specific — always include file:line references for issues.
- Verdict must be justified — every SHIP/FIX/BLOCK needs evidence from actual commands.
- Don't auto-fix code — report issues and add fix tasks to plan.md. Let
/buildfix them. Review only modifies plan.md, never source code. - Check acceptance criteria — spec.md is the source of truth for "done".
- Security is non-negotiable — any hardcoded secret = BLOCK.
- Fresh evidence only — run commands before making claims. Never rely on memory.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

