Skip to content

Add code-review skill for cross-agent diff review - #270

Open
blarghmatey wants to merge 2 commits into
mainfrom
tmacey/cross-agent-code-review
Open

Add code-review skill for cross-agent diff review#270
blarghmatey wants to merge 2 commits into
mainfrom
tmacey/cross-agent-code-review

Conversation

@blarghmatey

Copy link
Copy Markdown
Member

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/opencode
sessions the same diff-review capability Claude Code gets from its
built-in /code-review — correctness bugs plus
reuse/simplification/efficiency cleanups over a diff.

  • Ports the four-dimension rubric (correctness, simplification,
    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 finding
    gets re-checked against the actual code before it ships.
  • Target resolution covers no-arg (working tree diff), branch, path,
    and PR-number inputs, stated as prose rather than CLI flags, since
    not every platform this skill runs on has an argument-passing
    mechanism.
  • No effort-tier flag either, for the same reason — depth is read from
    the request ("be thorough" widens the pass) rather than a parameter.
  • Report-only by default; fixes only apply after the review is
    reported, and only when the request already asked for a fix.
  • No MCP or witan dependency — needs only git (and gh for a
    PR-number target), so it installs and runs the same on every
    platform in the catalog.
  • references/dimensions.md and references/findings-format.md
    carry the worked examples, mirroring address-pr-feedback's
    SKILL.md + references anatomy.
  • Registered in agent-config.toml's [skills] table and
    [profiles.process], and added to both skills/README.md and
    skills/process/README.md's catalogs, per AGENTS.md's "Adding a
    Skill" checklist.

How can this be tested?

  • prek run against all changed files (markdownlint, TOML checks,
    trailing-whitespace, secret detection) — all passed.
  • agent-kit validate agent-config.toml — no missing/mismatched
    entries; the only output is expected drift for skills not yet
    applied to this machine's install directories.
  • Manually walked the skill's own steps in this Claude Code session
    against a real diff (43fc1c6, path-scoped to
    mcp/servers/witan/witan/cli/{local_dispatch.py,_common.py} and
    config.py): the path-scoped target-resolution rule worked
    mechanically, and I produced an actual findings-table pass rather
    than only the worked examples in references/. Outcome: no
    high-confidence findings survived — one plausible-looking
    correctness concern (a non-remote target matching by match_paths
    could 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 precedence
    logic in witan_core.target_config, outside the 3-file scope of
    that 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.
  • Not done: a live second-platform run (pi/copilot/opencode), called
    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 only git diff, a rubric, and a
markdown 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.

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
Copilot AI balanced review requested due to automatic review settings August 20, 2026 22:09

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/HEAD is 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 reach merge-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; use HEAD for 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.

Comment thread skills/process/code-review/SKILL.md Outdated
Comment thread skills/process/code-review/SKILL.md Outdated
Comment thread skills/process/code-review/references/findings-format.md
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
@blarghmatey

Copy link
Copy Markdown
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants