65 lines
5.7 KiB
Markdown
65 lines
5.7 KiB
Markdown
---
|
|
name: code-review
|
|
description: Independently review changes against repository standards and the requested behavior using a pinned Git diff. Use for branch, PR, work-in-progress, or workflow-record review, with targeted follow-up after fixes.
|
|
---
|
|
|
|
# Code review
|
|
|
|
Use one independent, read-only reviewer by default. Assess two axes and report them separately:
|
|
|
|
- **Standards:** repository instructions and documented conventions.
|
|
- **Specification:** the originating request, issue, spec, or workflow record.
|
|
|
|
Add specialist reviewers when distinct risk or repository policy warrants them, not merely because there are two axes. The agent that authored or mutated the diff cannot review it or its own remediation.
|
|
|
|
## 1. Pin the review bytes
|
|
|
|
Resolve a fixed point from the caller's brief or workflow record; ask only when the intended scope cannot be established. Record:
|
|
|
|
- review base and immutable product HEAD commits, never mutable `HEAD` in the brief;
|
|
- clean status, product tree hash, and `git log <base>..<product-head> --oneline`;
|
|
- exact command `git diff --binary --full-index --find-renames <base>...<product-head> --`;
|
|
- SHA-256 of those exact bytes, generated by the parent.
|
|
|
|
Stop on a bad ref, dirty product state, or empty diff unless an empty comparison was expected. During a development workflow, review after focused checks and before the final full suite so fixes do not cause scheduled duplicate suite runs. Independent review does not establish test success.
|
|
|
|
## 2. Resolve specification and standards
|
|
|
|
Use the caller's explicit request, supplied spec, or retained workflow record as the primary specification. Otherwise inspect linked issues (using repository issue-tracker instructions when configured) or matching repository docs. Ask only when the intended behavior remains unclear. A workflow record needs no issue-tracker configuration or ceremonial plan approval to be a valid specification.
|
|
|
|
If the user explicitly requests standards-only review without a specification, report “specification not assessed”; do not claim both axes passed.
|
|
|
|
Collect applicable `AGENTS.md`, `CLAUDE.md`, contributing, coding-standard, and ADR sources. Where repository standards do not override it, consider this judgment-based baseline and skip tooling-enforced issues:
|
|
|
|
- Names hide purpose; duplicated logic obscures a shared contract.
|
|
- Feature envy, data clumps, primitive obsession, or repeated switches complicate change.
|
|
- Shotgun surgery or divergent responsibilities scatter one change across unrelated areas.
|
|
- Speculative generality, middlemen, message chains, or inappropriate inheritance add indirection without a current need.
|
|
|
|
Distinguish consequential defects and documented violations from optional style preferences. Do not require speculative abstractions, compatibility paths, or exhaustive tests without a concrete contract or risk. Judge coverage against changed behavior and credible failures.
|
|
|
|
## 3. Enforce independence and read-only review
|
|
|
|
List every author/mutator by display name and stable child/session identity when exposed. Select a reviewer outside that set with repository read access and Git-capable `bash`, but no declared `write`, `edit`, or nested-agent tools. When identity cannot be distinguished, exclude the ambiguous profile/run rather than assuming independence.
|
|
|
|
Capture branch, HEAD, status, tree hash, and changed paths before review. Launch the reviewer directly with the pinned commits, exact diff command and digest, specification, standards, mutator exclusions, and identity-reporting requirement. Require the reviewer to:
|
|
|
|
1. Regenerate the exact diff and confirm its SHA-256 before analysis.
|
|
2. Remain read-only, run no mutating commands, and perform no remediation.
|
|
3. Assess both axes, grounding findings in file/hunk evidence and severity; quote the requirement for specification findings.
|
|
4. Report identity when exposed and stay under 400 words unless complexity warrants more.
|
|
|
|
After delivery, verify Git state is unchanged. Missing output, digest mismatch, mutator overlap, or reviewer mutation means no valid verdict. Mutation also makes that reviewer ineligible for subsequent review of the diff.
|
|
|
|
## 4. Report findings and remediate
|
|
|
|
Present `## Standards` and `## Specification`, separating documented violations from judgment-based concerns. Preserve each axis's findings and severity; report approval explicitly when no material findings remain. Keep optional suggestions non-blocking unless tied to a requirement or concrete risk.
|
|
|
|
Validate findings against repository evidence. An original implementer or another non-reviewer makes accepted fixes, then runs affected checks. Use [verification policy](../develop-workflow/references/verification.md) for evidence reuse and final-suite timing; obey stricter repository requirements.
|
|
|
|
For bounded corrections, resume the same independent reviewer with the previous verdict, old and new pinned commits/digests, fix delta, and check results. Require it to inspect fixes and affected interactions, confirm the new full-diff fingerprint, and state which prior conclusions remain applicable. A prior verdict alone never approves later product changes.
|
|
|
|
Request a broader fresh review when scope, architecture, shared behavior, or uncertain interactions invalidate previous conclusions; use a new specialist identity only when useful or required. Ask the user only for changed requirements, approval-boundary risk, or an unresolved decision, not because an automatic remediation cycle count expired. Stop repetitive ineffective retries, reassess the cause, and surface blockers honestly.
|
|
|
|
**Complete when:** independent review covers the final pinned product diff, applicable axes have no unresolved material findings, and before/after evidence proves the reviewer stayed read-only. Final test completion remains a separate integration requirement.
|