From em-software-factory
Run comprehensive code review using parallel agents, then synthesize findings
How this skill is triggered — by the user, by Claude, or both
Slash command
/em-software-factory:code-reviewThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Run a comprehensive code review using parallel agents, then synthesize findings.
Run a comprehensive code review using parallel agents, then synthesize findings.
The goal is to catch real problems — bugs, security holes, and code that will be hard to maintain. Perfection is a matter of opinion. A good PR review is direct and kind, not exhaustive.
Determine what code to review using this priority:
git diff main...HEAD)git diff --staged)git show HEAD)Examples:
ghReview only what changed. Agents should report issues in the diff or code directly affected by the change. Do not report pre-existing issues in unrelated files.
After determining scope, find related documents before launching agents:
Extract identifiers from branch name and PR title:
feat/SEMI-1234-description → SEMI-1234)Search for related documents using Glob:
specs/features/*{ticket}*/implementation-plan*.mdspecs/research/*{ticket}*.md or specs/research/*{keyword}*.md.claude/cache/SEMI-{ticket}.md (cached Jira tickets).claude/cache/CONF-*.md (cached Confluence pages)Record discovered paths for inclusion in the review document later.
This step is lightweight — just glob for matching filenames, don't read the documents. The paths are included in the saved review document so context can be found later.
Assess the diff before launching agents:
Use a single message with multiple Agent tool calls:
Run relevant tests for the changed files. Report:
Run linters for the changed files.
Report:
First, check if skills.md or a similar project style guide exists. If so, read it to understand project conventions.
Review the code changes and provide up to 5 concrete improvements, ranked by:
Only include genuinely important issues. If the code is clean, report fewer items or none.
Format each suggestion as:
1. [HIGH/MED/LOW Impact, HIGH/MED/LOW Effort] Title
- What: Description of the issue
- Why: Why this matters
- How: Concrete suggestion to fix
Focus on non-obvious improvements - skip formatting, naming nitpicks, and things linters catch.
Review the code changes for security concerns:
Calibrate severity to the trust boundary. Internal tooling where inputs are controlled by developers is lower risk than user-facing application code. For example, an unquoted variable in a script that receives input from git diff --name-only is not the same severity as command injection in a web handler.
Also check error handling:
Report issues with severity (Critical/High/Medium/Low) and specific file:line references. If no issues found, report "No security concerns identified."
First, check if skills.md or a similar project style guide exists. If so, read it to understand project conventions.
Review the code changes for quality and style issues:
Quality:
Style Guidelines: 4. Naming conventions - does naming match project patterns and style guide? 5. File/folder organization - are files in the right place? 6. Architectural patterns - does code follow established patterns in the codebase? 7. Consistency - does new code match the style of surrounding code? 8. Project conventions - does code follow rules in the project style guide (if present)?
For each issue found, provide:
If code is clean, report "No quality or style issues identified."
Review test coverage and quality for the changed code:
Coverage (with ROI lens):
Quality:
Test Code Quality:
Flakiness Risk:
Anti-patterns:
Report issues with specific suggestions. If tests are well-balanced, report "Test coverage is appropriate and behavior-focused."
Review the code changes for performance concerns:
For each concern, explain the impact and suggest a fix. If no concerns, report "No performance concerns identified."
Review changes for dependency, compatibility, and deployment concerns:
Dependencies (if package files changed):
Breaking Changes (if public APIs or exports changed):
API Contract Changes (TREAT AS HIGH RISK):
Deployment Safety:
Observability:
Report issues with specific file references. If no concerns, report "No dependency, compatibility, or deployment concerns."
Review the code changes with fresh eyes, asking "could this be simpler?"
Simplification:
Maintainability ROI:
Look for:
Change Atomicity & Reviewability:
For each finding, explain:
If the code is appropriately simple and atomic, report "Code complexity is proportionate to the problem and changes are well-scoped."
Before triaging, assess the scope of the diff. A small, focused change (bug fix, config tweak, minor refactor) deserves a short review. Do not produce a detailed report for a trivial change — that wastes the author's time and buries real signal in noise. Match the depth of your output to the complexity of the change.
Collect all agent results and triage into three buckets:
Blockers — must be fixed before merge:
A blocker should fail the "would a senior engineer hold the PR for this?" test. Missing config sections, follow-up improvements, and nice-to-haves are suggestions, not blockers.
Suggestions — worth considering but not blocking:
Nits — drop entirely. Do not include in output.
Prune suggestions ruthlessly — only include ones where acting on the feedback would meaningfully improve the PR.
Write findings as a colleague who read the code carefully, not as an audit report. Explain what you noticed and why it matters. Be direct and specific. Skip preamble.
If there are no blockers and no meaningful suggestions, skip the sections entirely and just write:
## Code Review
LGTM. No concerns.
Otherwise:
## Code Review
### Blockers (X)
1. [Bug] Title — file:line
What goes wrong and why.
2. [Security] Title — file:line
What the risk is and how to fix it.
### Suggestions (X)
1. [Quality] Title — file:line
Brief, specific description.
### Verdict: [Approve | Needs Work]
One sentence. Blockers require fixes before merge. Suggestions are at the author's discretion.
Omit any section that has no entries. Do not include an "All Clear" list of agents that found nothing.
Before presenting the review, pass the draft through one final agent. This agent is a very senior software engineer who has written and received thousands of code reviews. Their job is to review the review itself.
Give this agent the full draft review, the PR/branch title, and the diff size (files changed, lines added/removed). The agent should:
Read it as the author would. Is this review something you'd want to receive? Does it respect the effort that went into the PR? A first-time CI setup and a critical bugfix deserve different energy — match the tone to the PR's ambition.
Check severity calibration. Are any findings rated higher than a senior engineer would rate them? Downgrade or cut anything inflated.
Check length. A busy author should be able to read this in under 60 seconds and know exactly what to do. If the review is longer than the diff warrants, cut it down.
Check the bar. Would a reasonable senior engineer approve this PR with minor comments? If so, the verdict should be Approve, not Needs Work.
Rewrite as needed. The agent produces the final version of the review. This is what gets presented — not the earlier draft.
After synthesizing results, save the review to .claude/reviews/. This happens automatically — no user action needed.
.claude/reviews/{number}_review.md.claude/reviews/YYYY-MM-DD-{branch-name}-review.mdIf the file already exists, overwrite it. A code review is a point-in-time assessment — the old version is stale once the code changes. Git history preserves previous reviews.
Run these commands to collect metadata:
git rev-parse HEAD # current commit hash
git branch --show-current # current branch
basename $(git rev-parse --show-toplevel) # repository name
git config user.name # reviewer username
date -u +%Y-%m-%dT%H:%M:%SZ # current timestamp
Write the review document with this structure:
---
date: [ISO timestamp]
reviewer: [username]
git_commit: [commit hash]
branch: [branch name]
repository: [repo name]
pr_number: [PR number, omit if no PR]
scope: [branch diff | staged changes | commit {SHA} | PR {number}]
verdict: [Approve | Needs Work]
tags: [code-review, relevant-component-names]
status: complete
last_updated: [YYYY-MM-DD]
last_updated_by: [username]
---
# Code Review: [PR title or branch name]
**Date**: [ISO timestamp]
**Reviewer**: [username]
**Git Commit**: [commit hash]
**Branch**: [branch name]
**Scope**: [description of what was reviewed]
## Code Review Summary
[The full synthesized output — Blockers, Suggestions, and Verdict sections as formatted above. Or "LGTM. No concerns." if clean.]
## Related Documents
[List all documents discovered in the "Discover Related Documents" step. Only include categories where documents were found.]
- Implementation Plan: `specs/features/FEAT-XXX/implementation-plan.md`
- Research: `specs/research/YYYY-MM-DD-topic.md`
- Jira Ticket: `.claude/cache/SEMI-XXX.md`
- Confluence Page: `.claude/cache/CONF-123456789.md`
# Review current branch
/code-review
# Review specific PR
/code-review pr 123
/code-review https://github.com/org/repo/pull/123
# Review specific commit
/code-review commit abc123
# Review specific files
/code-review src/auth.ts src/users.ts
Recommended workflow:
/create-plan SEMI-790 - Create implementation plan/implement-plan SEMI-790 - Execute implementation/validate-plan - Verify success criteria/code-review - Comprehensive code reviewThe code review complements validation by focusing on code quality, security, and maintainability beyond just functional correctness.
npx claudepluginhub emergenceai/em-aisoftwarefactoryGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.