| name | brain-review |
| description | Principle-grounded review of code changes, PRs, or plans. Use when asked to review, critique, or assess quality of work — "review", "review this", "code review", "check this". |
Review
Thorough review grounded in project principles. Do NOT make changes — the review is the deliverable.
Use Tasks to track progress. Create a task for each step below (TaskCreate), mark each in_progress when starting and completed when done (TaskUpdate). Check TaskList after each step.
Step 1 — Load Principles
Read /Users/fujitanisora/brain/principles.md. Follow every [[wikilink]] and read each linked principle file. These principles govern review judgments — refer back to them when evaluating issues.
Do NOT skip this. Do NOT use memorized principle content — always read fresh.
Step 2 — Determine Scope
Infer what to review from context — the user's message, recent diffs, or referenced plans/PRs. If genuinely ambiguous (nothing to infer), ask.
Auto-detect review mode from change size:
- BIG CHANGE (50+ lines changed, 3+ files, or new architecture) — all sections, at most 4 top issues per section
- SMALL CHANGE (under those thresholds) — one issue per section
Step 3 — Gather Context
For SMALL CHANGE reviews, read files directly in the main context — delegation overhead exceeds the cost of reading a few files.
For BIG CHANGE reviews, delegate exploration to subagents via the Task tool.
Spawn exploration agents (subagent_type: Explore) to:
- Read the code or plan under review
- Identify dependencies, callers, and downstream effects
- Map relevant types, tests, and infrastructure
Run multiple agents in parallel when investigating independent areas.
Step 4 — Gather Domain Skills
Check installed skills (/Users/fujitanisora/.claude/skills/, .claude/skills/) for any that match the review's domain.
Invoke matched skills now — read their output and use domain guidance to inform your review.
For domains not covered by installed skills, use find-skills to search for a relevant skill.
Step 5 — Assessment Pipeline
Work through all sections in order. For each section, check against loaded principles.
1. Scope Check
If the review targets work against a plan phase:
- Read the plan phase that was assigned.
- Run
git diff --stat and git log --oneline for the relevant commits.
- Flag files changed outside the plan phase's stated scope as scope violations.
If no plan phase applies, skip this subsection.
2. Architecture
- System design and component boundaries
- Dependency graph and coupling
- Data flow patterns and bottlenecks
- Security architecture (auth, data access, API boundaries)
3. Code Quality
- Code organization and module structure
- DRY violations — be aggressive
- Error handling patterns and missing edge cases (call out explicitly)
- Over-engineering or under-engineering relative to principles; consider redesign-from-first-principles
- Technical debt hotspots
4. Tests
- Coverage gaps (unit, integration, e2e)
- Test quality and assertion strength
- Missing edge case coverage — be thorough
- Untested failure modes and error paths
- New behavior must have new tests. Tests must assert outcomes, not implementation details.
5. Performance
- N+1 queries and database access patterns
- Memory-usage concerns
- Caching opportunities
- Slow or high-complexity code paths
Principle Compliance
For each changed file, check against loaded principles. Common violations:
- Bolted-on changes instead of redesign (redesign-from-first-principles)
- Missing verification (prove-it-works)
- Unnecessarily added complexity (subtract-before-you-add)
Step 6 — Issue Format
NUMBER each issue (1, 2, 3...). For every issue:
- Describe the problem concretely with file and line references
- Assign severity: high (blocks acceptance), medium (worth fixing, multiple may block), low (style/minor)
- Present 2–3 options with LETTERS (A, B, C), including "do nothing" where reasonable
- For each option: implementation effort, risk, impact on other code, maintenance burden
- Give a recommended option and why, mapped to principles
- Ask whether the user agrees or wants a different direction
Severity Guide
- high: Incorrect behavior, missing tests for new behavior, scope violation on core files, principle violation that changes architecture.
- medium: Worth fixing but not blocking on its own. Multiple mediums may trigger rejection.
- low: Style, documentation, minor improvements. Note but don't block on these.
When using AskUserQuestion, label each option with issue NUMBER and option LETTER. Recommended option is always first.
Step 7 — Verdict
After presenting all issues, give an overall verdict:
- Accept: All checks pass, scope clean, tests present and passing.
- Accept with notes: Low-severity issues only. List them for optional follow-up.
- Revise: High-severity issues found. Include specific actionable feedback — reference the exact file, line context, and principle violated.
Interaction Rules
- Do not assume priorities on timeline or scale
- Do not make changes — present findings and wait for direction
- Present all sections together, then ask for feedback once at the end
- Per prove-it-works: if something can be tested, note how in the issue description
