Skip to content

m3dcodie/eng-flow / .claude/skills/eng-flow-code-review

eng-flow-code-review

Unverified

Production Stage 6 — reviews an implemented diff (branch vs. base, or a specific story's commits) across five axes before it ships. Post-implementation counterpart to Stage 3.5's pre-implementation architecture review — this one reviews actual code, not a design doc.

eng-flow code review

Stage 6 of the production track. Reviews the actual diff produced by Stage 5's implementation loop — the post-implementation counterpart to Stage 3.5, which reviewed architecture.md before any code existed. Runs before the diff ships.

Analytics

At the start of every step below (including Step 0), run python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-analytics-checkpoint" eng-flow-code-review "<step name>" "<story-slug>". As the last action of Step 7, run python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-analytics-finish" eng-flow-code-review "<story-slug>". See eng-flow-spec's Analytics section for what this logs and why; rollup via eng-flow-analytics (Stage 10).

Decision Ledger

Check $ARGUMENTS for a --guide token; if present, every decision point below gets an explicit AskUserQuestion instead of a silent default, and Step 7's report adds a "Decisions I made / decisions you made" summary. Log every decision point via python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-decision-log" eng-flow-code-review "<step>" <reason> <mode> <owner> "<description>" "<story-slug>". See eng-flow-spec's Decision Ledger section for the taxonomy and why. Rollup/analysis: eng-flow-retro Step 1 (Stage 9).

Findings Ledger

Step 7 logs the severity-tagged finding counts it already computed for code-review.md to project-level eng-flow/findings.jsonl, via eng-flow-findings-log — see Step 7 for the exact call. Feeds eng-flow-analytics' (Stage 10) bug-rate rollup; not something this skill reads back itself.

Step 0 — Scope

Default to the current branch's diff against its base branch. If that's ambiguous (detached HEAD, no clear base, or the user named something specific — a story, a file, a commit range), ask via AskUserQuestion rather than guessing. Log it: risk <silent_decide|open_question> <ai_default|user_confirmed> "scope: <what was reviewed>".


Step 1 — Context

Find the story this diff implements (eng-flow/backlog/stories/<story-slug>.md and its tasks.md, if one exists). Read the acceptance criteria — review is grounded in what was supposed to happen, not a vibe check. If no story/task exists for this diff, proceed without it, but say so in the report. Log it: risk silent_decide ai_default "no story found for this diff — reviewed without acceptance-criteria grounding" when that applies.

Also look for eng-flow/security-policy.md (project-level, optional — established at Stage 3 if the project has one). Read it if present; Step 3's Security axis and Step 3.5's security subagent check the diff against it.


Step 2 — Tests first

Before reading implementation code, check the tests:

  • Do tests exist for the change?
  • Do they test behavior, not implementation details?
  • Are edge cases and error paths covered, not just the happy path?
  • Would they actually catch a regression if this code changed later?

Step 3 — Five-axis review

Reused from agent-skills' code-review-and-quality (attribution: docs/DECISIONS.md). For each file in scope:

  1. Correctness — matches the story's acceptance criteria; edge cases and error paths handled; no off-by-one/race/state-consistency issues.
  2. Readability & simplicity — names are clear; control flow is straightforward; no clever tricks that should be simplified; could this be done in fewer lines; are abstractions earning their complexity (don't generalize before a third use case); any dead-code artifacts (unused vars, backwards-compat shims, // removed comments).
  3. Architecture — follows existing patterns or justifies a new one; no unjustified duplication; dependencies flow the right direction; abstraction level appropriate; a "cleaner" refactor should reduce the number of concepts a reader holds, not just relocate them.
  4. Security — input validated at boundaries; no secrets in code/logs; auth/authz checked where needed; queries parameterized; external data treated as untrusted. If eng-flow/security-policy.md exists, check the diff against each of its stated rules explicitly (e.g. credential scope, where secrets are read from, confirmation before state-mutating operations) — a violation is a finding like any other, tagged with the rule it breaks.
  5. Performance — no N+1 patterns; no unbounded loops/fetches; no unnecessary work in hot paths; pagination on list endpoints where relevant.

When flagging a structural problem, propose the specific remedy (extract a helper, replace a conditional chain with a dispatcher, separate orchestration from business logic) — not just "this is complex."


Step 3.5 — Independent subagent pass

Step 3 ran in this conversation — often the same one that wrote the diff. Counter self-review bias with independent passes, dispatched via the Agent tool, foreground (their output feeds Step 5). Give each subagent only what it needs to review — not this conversation's context or Step 1-3's findings.

Both subagents are plugin agents under agents/, read-only (no Write or Edit), and carry their own review instructions. Call each by subagent_type and pass only the run-specific inputs below.

Always — one blind adversarial subagent, subagent_type: "eng-flow:eng-flow-adversarial-reviewer". Prompt: the diff scope from Step 0 (git diff <base>...HEAD or equivalent).

Conditionally — one security-specialist subagent, if the diff touches auth, payments, secrets, PII, data access, or config/session handling, or if eng-flow/security-policy.md exists in the project (a standing policy means every diff gets checked against it, not just the ones that look security-shaped). Skip it and say why if neither applies. Log it: risk silent_decide ai_inferred "security subagent: <dispatched | skipped — reason>". Use subagent_type: "eng-flow:eng-flow-security-reviewer" (its prompt is adapted from agent-skills' security-auditor persona; attribution: docs/DECISIONS.md). Prompt: the diff scope from Step 0, plus eng-flow/security-policy.md if it exists.

Fallback: if either agent isn't in the Agent tool's list (the plugin agents didn't load — e.g. the skills are running from a checkout, not an installed plugin), read ${CLAUDE_PLUGIN_ROOT}/agents/<name>.md (agents/<name>.md in an eng-flow checkout), and send its body below the frontmatter, followed by the same inputs, as the prompt of a general-purpose Agent call. Log it: risk silent_decide ai_default "agent <name> unavailable: general-purpose fallback". Never skip the review because the agent is missing.

If both trigger, dispatch both Agent calls in the same assistant turn so they run in parallel. If a subagent fails or times out, note it and continue — the structured Step 3 review still stands on its own.

Merge each subagent's findings into Step 4's severity list, tagged by source (five-axis / adversarial / security specialist). Drop exact duplicates; keep independent findings that reach the same conclusion — that agreement is informative, not redundant.


Step 4 — Severity and gating

Tag every finding:

TagMeaningGating
CriticalBlocks merge — security hole, data loss, broken functionalityOne AskUserQuestion per finding, stop and wait
RequiredMust address before mergeOne AskUserQuestion per finding, stop and wait
NitMinor, optional — author may ignoreList in report, no individual gate
Optional / ConsiderWorth considering, not requiredList in report, no individual gate
FYIInformational onlyList in report, no individual gate

Lead with what matters — correctness and security first. Don't bury a real Critical/Required finding under a pile of Nits; if there's one structural problem and ten nits, the structural problem is the review.

For each Critical or Required finding, state the issue, its source tag, the recommendation, and why — then stop and wait for the user's explicit response before raising the next one, same discipline as every other eng-flow stage. Don't assume the obvious fix and move on.

Log each: risk must_escalate user_confirmed "[<severity>] <title>: <resolution>" — Critical/Required findings are always must_escalate, guide mode or not.


Step 5 — Dead code check

If the diff leaves anything orphaned (a function/component/constant nothing calls anymore), list it explicitly and ask before removing it — don't delete silently, don't leave it lying around unmentioned either. Log it: risk open_question user_confirmed "orphaned code '<name>': removed|kept" when anything's found.


Step 6 — Verify the verification

Confirm: tests pass (run them), build succeeds (run it), and — if this touches UI — note that a manual check is still owed (this skill doesn't drive a browser; that's eng-flow-qa, Stage 7).


Step 7 — Save and report

Write findings to eng-flow/backlog/stories/<story-slug>/code-review.md (or, if no story was found in Step 1, report inline without saving):

# Code Review: [scope — branch/story name]
(source story: eng-flow/backlog/stories/<story-slug>.md, if found)

## Findings
### [Severity] [Title]
**Source:** [five-axis | adversarial | security specialist]
**File:** [path:line]
**Issue:** [...]
**Resolution:** [Fixed | Deferred — reason | Won't fix — reason]

## Verification
- Tests: [pass/fail, command run]
- Build: [pass/fail, command run]

## Verdict
[Approve | Request changes]

Report the verdict and a summary of what was fixed vs. deferred.

If this run was in guide mode, add a "Decisions I made / decisions you made" summary here, drawn from this run's eng-flow-decision-log calls.

Log the bug-rate rollup: python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-findings-log" eng-flow-code-review "<verdict>" <critical-count> <required-count> <nit-count> "<story-slug>". The ledger only has three buckets (shared with eng-flow-qa's simpler vocabulary) — Step 4's five severities collapse into it as Critical→critical, Required→required, and Nit + Optional/Consider + FYI (all three are "no individual gate" tiers) summed into the nit-count. Counts are of findings caught this pass, regardless of whether they were fixed inline; this feeds eng-flow-analytics' (Stage 10) bug-rate rollup, not a code-quality score.

Run the Step 7 analytics-finish call (see Analytics section above) before ending.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 318kUpdated Claude CodeCodexUnverifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall