code-review

Code Review — Deep Codebase Audit & Technical Review Skill

You perform thorough technical reviews — from deep code audits to architecture decisions and security assessments. For code audits, you find the gaps that cause bugs in production: functions nobody calls, errors nobody sees, features half-built, and code that should be deleted. For broader reviews, you analyze decisions from multiple specialist perspectives and produce structured recommendations.

CRITICAL RULES

1. Every finding must include file:line references. No vague "somewhere in the code" findings.
2. Categorize by severity. CRITICAL > WARNING > PRUNE > INFO. Read resources/severity-guide.md.
3. Run ALL passes. Don't skip passes because early ones found nothing. Read resources/audit-passes.md.
4. Never suggest adding code without showing what to remove. This is a pruning exercise, not a feature request.
5. Focus on real bugs, not style. Don't flag formatting, naming conventions, or missing comments unless they actively cause confusion or bugs.
6. Provide the fix, not just the finding. Each finding should say what to do about it.

Review Modes

This skill operates in two modes depending on the request:

Mode 1: Code Audit (default)

"review the code", "audit the code", "find dead code", "code cleanup"

Deep 7-pass audit of a codebase. Produces an audit report with file:line findings grouped by severity. See Audit Architecture below.

Mode 2: Technical Decision Review

"architecture decision", "security audit", "design review", "refactoring plan", "deployment review"

Multi-perspective analysis of a technical question or decision. Produces a structured decision document. See Technical Decision Review below.

Determine the mode from the user's request. If ambiguous, default to Mode 1 for "review" requests that reference code/files, and Mode 2 for questions about architecture, technology choices, or design decisions.

---

MODE 1: CODE AUDIT

Audit Architecture

The review runs 7 passes over the codebase. Each pass looks for a different class of problem. The passes are ordered from most critical (broken functionality) to least critical (cleanup opportunities).

Pass 1: WIRING          — Is everything connected end-to-end?
Pass 2: ERROR HANDLING   — Can failures be seen and debugged?
Pass 3: COMPLETENESS     — Are features fully implemented?
Pass 4: DEAD CODE        — What can be deleted right now?
Pass 5: BLOAT            — What's too big, too complex, or redundant?
Pass 6: HARDCODING       — What should be configurable but isn't?
Pass 7: SECURITY         — Any obvious vulnerabilities?

Read resources/audit-passes.md for the detailed checklist for each pass.

Workflow

Phase 1 — Scope the Review

Before auditing, understand the codebase:

1. What's the project? Read README, README.md, package.json, etc.
2. What's the tech stack? Framework, language, build tools
3. What's the architecture? Entry points, services, stores, components
4. What was recently changed? If there's git history, focus on recent additions

Build a mental map of the codebase:

• Entry point → Router → Pages → Components → Stores → Services → External APIs
• Trace the full data flow from user action to persistence and back

Phase 2 — Run the 7 Audit Passes

For each pass, use Grep and Glob to systematically search for the patterns described in resources/audit-passes.md.

Use runSubagent to run parallel agents when the codebase is large. Delegate independent passes to separate agents via runSubagent and wait for each response:

• Agent 1: Passes 1-2 (Wiring + Error Handling) — these are related
• Agent 2: Passes 3-4 (Completeness + Dead Code) — these are related
• Agent 3: Passes 5-7 (Bloat + Hardcoding + Security) — lighter passes

Phase 3 — Cross-Reference

After individual passes, cross-reference findings:

• Does a "dead code" finding explain a "wiring" gap? (function exists but never called)
• Does a "completeness" gap overlap with a "placeholder" finding?
• Deduplicate — one root cause might show up in multiple passes

Phase 4 — Compile the Report

Output format (read resources/report-format.md):

# Code Review Report — [Project Name]
Date: [date]
Files Scanned: [count]
Findings: [count] (X critical, Y warning, Z prune, W info)

## CRITICAL — Must Fix
These cause broken functionality, data loss, or security holes.

### CR-001: [Title]
**File:** `src/stores/game-store.ts:108`
**Pass:** Wiring
**Problem:** `submitGameSession()` is defined in dataverse.ts but never called.
Game results are never persisted to Dataverse.
**Fix:** Call `submitGameSession()` from the `endGame()` action in game-store.ts.

## WARNING — Should Fix
These cause degraded experience, silent failures, or maintainability issues.

## PRUNE — Consider Removing
Dead code, redundant logic, bloated files. Removing these makes the codebase
leaner and easier to maintain.

## INFO — Minor Observations
Nice-to-know items that don't require action.

Phase 5 — Pruning Recommendations

After the main audit, generate a pruning plan. Read resources/pruning-guide.md.

The pruning plan should:

1. List files/functions/types that can be safely deleted
2. List files that should be split (too many responsibilities)
3. List abstractions that should be inlined (used only once)
4. List dependencies that can be removed from package.json
5. Estimate the total lines of code that would be removed

Validation Loop

After generating the report, verify every finding: confirm the file exists, the line number matches the reported issue, and the severity is justified. If a finding is stale or incorrect, remove it. Re-run any grep patterns that returned 0 results to confirm they were truly clean.

Without Agent Teams

If running as a single agent, execute passes sequentially. Prioritize passes 1-3 (Wiring, Error Handling, Completeness) as these find the most impactful issues. Passes 4-7 are still valuable but can be deferred if time-constrained.

References

• resources/audit-passes.md — Detailed checklists with grep patterns and manual checks for all 7 passes
• resources/severity-guide.md — CRITICAL / WARNING / PRUNE / INFO classification with examples and escalation rules
• resources/report-format.md — Full report template with finding format, grading scale, and finding ID convention
• resources/pruning-guide.md — Pruning decision tree, categories, safe-delete criteria, and anti-patterns to avoid
• resources/decision-template.md — Mode 2 decision document template
• resources/power-platform-context.md — Power Platform-specific review considerations

---

MODE 2: TECHNICAL DECISION REVIEW

Use this mode when the request is about evaluating a decision, reviewing architecture, assessing security posture, or producing recommendations — not auditing specific code.

When to Use Mode 2

Task Type	Example Request
Architecture Decision	"Should we use REST or GraphQL?"
Security Audit	"Review our auth model and table permissions"
Feature Design Review	"Is this feature design complete before we build?"
Refactoring Plan	"Should we restructure the service layer?"
Deployment Strategy	"Review our ALM and CI/CD approach"

Workflow

Step 1 — Understand the Question

Before analyzing, clarify:

• What is being decided or reviewed?
• Scope — Which files, components, or systems?
• Constraints — Timeline, budget, existing tech stack?
• Goals — What outcome is desired?

Ask the user if the request is vague. Don't start analysis until you know what you're analyzing.

Step 2 — Gather Context

Read relevant code, documentation, and workspace structure. Search for related patterns. Build enough understanding to evaluate from multiple angles.

Step 3 — Multi-Perspective Analysis

Evaluate the subject from each relevant perspective below. Skip perspectives that don't apply to the task (e.g., skip ALM for a pure code structure decision).

Architecture (System Design)

• Design patterns, scalability, maintainability
• Component boundaries and coupling
• Technology choices and their trade-offs
• Long-term viability and extensibility

Code Quality & Security

• Code complexity, anti-patterns, code smells
• OWASP Top 10 vulnerabilities
• Input validation, auth/authz, data exposure
• Dependency vulnerabilities

Testing & Quality

• Testability of the approach
• Edge cases and failure modes
• What tests are needed before/after this change
• Quality gates

Operations & ALM (when applicable)

• Environment strategy, deployment approach
• Solution architecture, source control
• Monitoring, logging, rollback strategy

Documentation (when applicable)

• Is the decision documented for future developers?
• Are API contracts clear?
• Is onboarding information adequate?

Step 4 — Challenge Assumptions

After the analysis, challenge your own findings:

• What assumptions did you make? Are they valid?
• What edge cases haven't been considered?
• What happens at scale (10x data, 10x users)?
• What's the cost of being wrong?
• What alternatives were not considered?

Step 5 — Produce Decision Document

Use the template from resources/decision-template.md. The document must include:

1. Executive summary with clear recommendation
2. Analysis from each relevant perspective
3. Alternatives considered with trade-offs
4. Risks and mitigation strategies
5. Prioritized action items

Power Platform Context

If the workspace contains Power Platform artifacts (Dataverse solutions, power.config.json, .pcfproj, Power Pages config) or the task mentions Dataverse/Power Apps/Power Pages, read resources/power-platform-context.md for platform-specific considerations to include in your analysis.