# Expert Review

> Conduct a thorough project-wide code review as an expert panel, cross-referencing specs, changelogs, and design documents

- Skill: `georgeqle/expert-review` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add georgeqle/expert-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/georgeqle/expert-review/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: GeorgeQLe (https://skillmd.com/u/georgeqle)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/georgeqle/expert-review

---


# Expert Review

Invoke as `$expert-review`.

Use this skill when the user wants a code review of the whole project or a specific path, with findings validated against project documentation.

## Process

1. Gather project context:
   - Read CLAUDE.md, README, and project config to understand conventions.
   - Search for and read specs (`specs/`, `spec.md`, `docs/`), changelogs (`CHANGELOG.md`, `tasks/history.md`), ADRs, interview logs (`*-__interview.md__`), and design docs.
   - Read `tasks/roadmap.md` if it exists to understand the full plan. Read `tasks/todo.md` for current phase and in-progress work. Read `tasks/manual-todo.md` (if it exists) for pending manual tasks. Read `tasks/record-todo.md` and `tasks/recurring-todo.md` (if they exist) for advisory context only.
   - Build a mental model of intentional decisions and documented trade-offs.
2. If the user provides a file or directory, scope the review there. Otherwise review the repository broadly.
2a. With `--adversarial-diff`, review the integrated diff and relevant surrounding code against the goal, plan, specifications, and verification evidence from a fresh context that did not implement or integrate the change.
2b. With `--read-only`, do not modify repository files, task documents, prompt history, alignment pages, the index, branches, commits, refs, or external state. This overrides every mutation-producing instruction in this skill, its Alignment Page and Default Shipping Contract conventions, project task-management rules, and prompt-history capture for the delegated invocation. Sol must capture any required delegation prompt/history before Terra starts. Delegated Terra review requires both flags and follows `docs/codex-accountable-agent-workflow.md`.
3. Read enough of the codebase to understand the architecture before critiquing it.
4. Review against these dimensions:
   - Correctness
   - Security
   - Performance
   - Architecture
   - Error handling
   - Code quality
   - Testing
   - Dependency risks
   - Spec conformance — code that diverges from documented specs or design decisions
5. Cross-reference each finding against documentation before reporting:
   - If a pattern is an intentional documented decision, do not report it as an issue — list it under "Documented decisions" instead.
   - If code diverges from a spec, flag it as a spec conformance issue.
6. Verify findings (false-positive filter):
   - Re-read the actual source code for every finding. Confirm: the code behaves as claimed, the issue isn't handled elsewhere (guard clause, middleware, caller), flagged dependencies actually exist/are missing, and "missing" test coverage isn't in a different test file.
   - Drop any finding you cannot re-confirm on second read. If uncertain, downgrade to Low with a note that it needs manual verification.

## Output

Report findings grouped by severity:

- Critical: bugs, security issues, data-loss risks
- High: major performance, architecture, or error-handling problems
- Medium: maintainability or testing gaps with real impact
- Low: worthwhile improvements with limited risk
- Spec conformance: where code diverges from documented specs, with document reference
- Documented decisions (no action needed): patterns that look like issues but are intentional
- Positive observations: strong patterns worth preserving

In delegated Terra mode, every non-stylistic finding also includes a stable ID, file and line evidence, impact/failure mode, recommended remediation, verification method, and `high|medium|low` confidence. Report `no findings` explicitly when none survive verification.

## Follow-Through

After presenting findings, write Critical and High implementation fixes to `tasks/todo.md` under a `## Code Review Fixes` heading (append or replace existing section), except when `--read-only` is active. One checkbox per finding with file:line and recommended fix. Do not add Medium/Low items. If a Critical/High observation is a non-blocking future validation or condition-gated measurement rather than a fix, write it to `tasks/record-todo.md` with source, condition, non-blocking reason, evidence, and promotion rule. Suggest `$exec` or `$investigate` to start fixing concrete work.

## Constraints

- Include concrete file and line references for each finding when possible.
- Every finding should include a specific recommended fix.
- Do not fill the review with style nitpicks.
- Never flag an intentional design decision as an issue. Respect documented trade-offs.
- If no project documentation exists, note the absence and recommend establishing specs or ADRs.


## Alignment Page

Follow the shared alignment-page convention via the packaged convention resolver; output path is `alignment/expert-review-{topic}.html`.

Skip alignment-page creation when `--read-only` is active.

## Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.

Skip all shipping, commit, push, task-document, and prompt-history mutations when `--read-only` is active.