Add code-review skill for cross-agent diff review - #270
Conversation
Claude Code's built-in /code-review has no equivalent on pi/copilot/ opencode, so those sessions have no portable way to review a diff for correctness bugs and reuse/simplification/efficiency cleanups. Ports the dimension set and the address-pr-feedback verify-before-reporting discipline (#251) into a skill that needs only git and a rubric — no MCP or witan dependency, so it works the same everywhere the skill catalog installs. Manually exercised in this session against mcp/servers/witan/witan/ cli/local_dispatch.py's diff (43fc1c6): target resolution and the findings table format both held up. A second-platform run (pi/copilot/ opencode) was not performed live and is still open per the task spec. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jo8EuXWhoatPDqfp1X7jng
There was a problem hiding this comment.
Pull request overview
Adds a portable cross-agent code-review skill with scope resolution, review dimensions, verification guidance, and standardized reporting.
Changes:
- Defines the code-review workflow and four-dimension rubric.
- Adds findings-format and review-dimension references.
- Registers and catalogs the new skill.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
skills/README.md |
Adds the skill to the main catalog. |
skills/process/README.md |
Adds the skill to the process catalog. |
skills/process/code-review/SKILL.md |
Defines review scope, verification, reporting, and fix mode. |
skills/process/code-review/references/findings-format.md |
Documents the findings schema and examples. |
skills/process/code-review/references/dimensions.md |
Documents the four review dimensions. |
agent-config.toml |
Registers the skill in the process profile. |
Suppressed comments (2)
skills/process/code-review/SKILL.md:42
refs/remotes/origin/HEADis optional and is often absent in local-only repositories or clones where the remote HEAD was not initialized. In those checkouts this command fails, so branch review cannot reachmerge-base, despite the stated portability. Define a fallback (for example, discover another remote's HEAD or ask the user for the base branch) rather than assuming this ref exists.
2. **A branch name** — diff against where it forked from the default
branch, not a plain two-dot diff: detect the default branch (`git
symbolic-ref refs/remotes/origin/HEAD`), find the merge base (`git
merge-base <default> <branch>`), then `git diff <merge-base>...<branch>`.
skills/process/code-review/SKILL.md:44
- A path-only review uses
git diff -- <path>, which shows only unstaged changes. If the requested path is staged, the skill reports an empty diff and misses the change; useHEADfor a working-tree path target and account for untracked files too.
3. **A path** — `git diff -- <path>` (or the branch-scoped equivalent above
if a branch was also named), same default-branch detection.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Copilot's PR review (#270) found three real issues, verified against live git behavior before fixing: - Scope rule 1 (no target) used git diff + git diff --staged only, which never show untracked files — a working tree with just one new file looked empty to both and silently fell back to reviewing HEAD~1 instead. Confirmed with a scratch `git init` + untracked file: both diffs empty. - Scope rule 2's origin/HEAD detection had no fallback. Confirmed a bare `git init` with no remote raises "not a symbolic ref" — a fresh or local-only checkout would break branch-target reviews outright. - Scope rule 3's `git diff -- <path>` only shows unstaged changes; confirmed a fully-staged change at that path produces an empty diff. Switched to `git diff HEAD -- <path>`. - The verification pass said the diff is "the evidence, already in context" while dimensions.md's own worked examples check callers and grep for existing implementations outside the diff, and the Depth section's promise to include lower-confidence findings on a deeper pass directly contradicted the verification pass's unconditional drop-if-unreproduced rule. Made the default-depth vs. widened-depth distinction explicit in both sections instead of leaving them to silently disagree. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jo8EuXWhoatPDqfp1X7jng
|
Addressed all review feedback in 8d61e36: 3 threads fixed and resolved (untracked-file gap, verification-pass/dimensions.md conflict, depth/verification drop-rule conflict). Copilot's 2 suppressed comments (missing origin/HEAD fallback, path-diff missing staged changes) had no separate thread to resolve but are fixed in the same commit. |
What are the relevant tickets?
N/A — tracked as an agent-kit workflow project task, no GitHub issue.
Description (What does it do?)
Adds
skills/process/code-review/SKILL.md, giving pi/copilot/opencodesessions the same diff-review capability Claude Code gets from its
built-in
/code-review— correctness bugs plusreuse/simplification/efficiency cleanups over a diff.
efficiency, reuse) and the "verify before reporting" discipline
already established in
address-pr-feedback(address-pr-feedback: verify claims, prove fixes, slow down on human review #251) — a findinggets re-checked against the actual code before it ships.
and PR-number inputs, stated as prose rather than CLI flags, since
not every platform this skill runs on has an argument-passing
mechanism.
the request ("be thorough" widens the pass) rather than a parameter.
reported, and only when the request already asked for a fix.
git(andghfor aPR-number target), so it installs and runs the same on every
platform in the catalog.
references/dimensions.mdandreferences/findings-format.mdcarry the worked examples, mirroring
address-pr-feedback'sSKILL.md + references anatomy.
agent-config.toml's[skills]table and[profiles.process], and added to bothskills/README.mdandskills/process/README.md's catalogs, perAGENTS.md's "Adding aSkill" checklist.
How can this be tested?
prek runagainst all changed files (markdownlint, TOML checks,trailing-whitespace, secret detection) — all passed.
agent-kit validate agent-config.toml— no missing/mismatchedentries; the only output is expected drift for skills not yet
applied to this machine's install directories.
against a real diff (
43fc1c6, path-scoped tomcp/servers/witan/witan/cli/{local_dispatch.py,_common.py}andconfig.py): the path-scoped target-resolution rule workedmechanically, and I produced an actual findings-table pass rather
than only the worked examples in
references/. Outcome: nohigh-confidence findings survived — one plausible-looking
correctness concern (a non-remote target matching by
match_pathscould mark local-store use "deliberate" and suppress the refusal
even when a differently-matching target elsewhere declares the real
deployment) turned out to hinge on
match_target()'s precedencelogic in
witan_core.target_config, outside the 3-file scope ofthat diff — so per the skill's own verification-pass rule, it didn't
ship as a finding. That's the report-nothing-if-nothing-survives
path working as designed, not a skipped step.
for in the task's definition of done. Flagging this as open rather
than claiming it — reviewer should treat that verification as
outstanding.
Additional Context
No
scripts/directory — steps need onlygit diff, a rubric, and amarkdown table, matching the "no MCP, no scripts" premise the spec
called for. If a reviewer finds the skill needs one in practice,
that's a signal the premise needs revisiting, not something to add
silently.