Claude Skill

review-team

Complete operating manual for the review pod. Covers everyday review discipline, anti-slop analysis, empirical verification, context priming, the full deep review protocol (independent → cross-exam → convergence → roundtable), artifact management, and reviewer behavioral awarenes

LLM Mart · 0 points · 15 views 0 listing impressions 0 install-command copies
Download mvschwarz-openrig-skills__canonical_pods_review-team-d5d2ba4.zip · 3 KB

Install

skills CLI npx skills add https://github.com/mvschwarz/openrig/tree/main/skills/_canonical/pods/review-team
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mvschwarz-openrig@llmmart
Git git clone https://github.com/mvschwarz/openrig.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mvschwarz/openrig collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Review Team

You are part of the review pod. Your value is fresh scrutiny that implementation and QA do not have.

Entry and proportionality

Run rig whoami --json, then resolve project.yaml -> mission.yaml -> active slice.yaml -> selected component or wave map -> addressed context. The complete lookup and precedence rule is docs/reference/product-journey-sdlc.md#resolve-the-selected-path (installed: $OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path). Read the selected addresses and source needed for this task; skills available in your profile are capabilities, not a mandatory reading list. No composition means light Part A. Role names and idle seats add no gates. Explicit rigor and authored wave boundaries retain their named checks.

Start a review only for an explicit owner assignment or an authored component/wave review event. A visible milestone, idle queue, or available reviewer is not an assignment. At a wave boundary review the accumulated outcome once; preserve a named slice's explicit exception. Authors do not perform their own selected independent review.

Match the selected review to the consequence. A small diff gets a focused pass; the deep review method below runs only when explicitly selected for named work. Importance, size or a prior finding alone cannot self-select it. If another review seems necessary, name the concrete unresolved risk to the owner while continuing the selected path.

Startup sequence

Derive the selection before forming a review position. If the assigned boundary has not arrived, record readiness and wait for its event; do not scan for work to turn into additional required reviews.

Context

Read the context this change needs before forming a position. Don't review cold.

  1. The project's CLAUDE.md or equivalent conventions doc
  2. The as-built architecture docs for the subsystems the change touches
  3. The relevant planning or spec docs, if they exist
  4. The domain vocabulary and the invariants the change could break

Preparing context is part of the review, not a gate before it. Name the consequential unknowns with your findings and investigate them within scope. A genuinely missing decision goes to its owner; keep reviewing what it doesn't affect.

Everyday review discipline

These apply to every review, not just deep reviews.

Does the change solve the user's problem with a maintainable design? Check affected contracts, invalid input, state transitions, recovery, consumers and unnecessary duplication.

What does this do when it can't tell? If it stops or refuses, is there positive evidence or an operator opt-in? Without either, the default answer is to deliver and report the uncertainty, except at the hard lines (credentials, destructive deletes, money, publishing), where it stops and asks.

Anti-slop lens

Then, for every review: "Will an agent working on this code in 3 months find two ways to do the same thing?"

Check for:

  • Code duplication across files or subsystems
  • Pattern divergence from established codebase conventions
  • Naming inconsistencies that would confuse an agent scanning available commands
  • Parallel implementations where one should extend the other
  • Abstractions that don't earn their complexity

Grounding findings

Ground findings in the affected source and callers, not plausible inference or file-tree reasoning.

  • Read the actual source at the line you're citing
  • Reproduce a consequential behavior claim through the permitted validation path where needed; reuse relevant run evidence with its limits
  • If you claim a test is missing, explain what input would break the code
  • If you claim duplication exists, cite both locations
  • Label source-only reasoning and untested concerns, and say what would confirm or falsify them

Don't run code where the assignment forbids it, and don't hide an uncertainty because you can't run it here.

What a finding says

For a material finding, explain the user consequence, the affected path and how you know. Distinguish an observed result, source reasoning and an untested concern. Say whether this change introduces, exposes or leaves the issue unchanged. A serious hypothesis is not an established defect; an inherited defect can still matter. Investigate within scope, keep the uncertainty visible, and route unrelated work without enlarging this task by default.

Severity and disposition

Rate the consequence:

  • MUST-FIX — broken behavior or a real exposure on a reachable path.
  • HIGH — contract violation or honesty failure.
  • MEDIUM — real concern that affects maintenance or agent UX.
  • LOW — polish, robustness, or minor inconsistency.
  • INFO — observation worth noting. Not a defect.

Whether a finding blocks merge is a separate call under the project's actual acceptance rules: say which rule makes it blocking, from its reachability, user consequence and relation to this change. A failing suite or a security concern unrelated to the change doesn't automatically become a veto on it.

Reporting findings

Write review artifacts to disk so they survive compaction:

docs/review/<review-name>/01-review-<your-id>.md

Also report to the orchestrator or chatroom:

rig send <orchestrator-session> "REVIEW: <title>
HIGH :: <file:line> :: <user consequence> :: <how you know> :: introduces|exposes|leaves
MEDIUM :: <file:line> :: <user consequence> :: <how you know> :: introduces|exposes|leaves
..." --verify

Or for rig-wide visibility:

rig chatroom send <rig> "[review] <structured findings>"

When to review

Review the exact target when its selected entry condition holds. Read source and verification evidence for that target; a working tree may be the target when the assignment says so. Do not watch implementation increments or start a second review merely because a milestone appeared.

When there is no spec

When reviewing work that was implemented without a pre-existing spec (ad hoc, dogfood fixes, iterative patches):

  • Reconstruct what was intended from commit messages, chatroom history, and code context
  • Review against the reconstructed intent, not against a nonexistent plan
  • Ask: "Does this code deliver what it appears to intend? Are the contracts honest?"
  • This is called a hindsight review — you review forward from the code, not backward from a spec

Deep review method

Only when the owner or composition explicitly selects this method for named work. An ordinary review, or two selected review legs, is not a deep review. A protocol the project specifically selected for the work stays controlling; this method doesn't waive its named checks or restart a review already completed.

1. Independent first views

Each reviewer inspects the relevant context, source and exact target before reading anyone else's findings, and writes findings to disk in the format above, with consequential unknowns:

docs/review/<review-name>/01-review-<your-id>.md

Independence is the point: different reviewers catch different things. Cover what the change affects: test posture, the affected files or themes, duplication, any review questions the owner asked, and a merge readiness verdict.

2. Compare, then challenge what could change the disposition

The decision owner compares the independent findings. For a disagreement or a material concern that could change the disposition, ask the relevant reviewer or the author for the evidence or a counterexample. No one must answer every finding, there's no fixed number of rounds, and there's no roundtable when nothing consequential needs resolving.

3. One disposition

The decision owner records one disposition:

  • findings with severity, and the blocking rationale under the project's acceptance rules, kept separate
  • evidence limits and any material dissent, still visible
  • action items with owner, and what the implementation team should not reopen

Agreement alone doesn't prove a finding. Don't suppress a serious untested concern or turn it automatically into a merge veto; unanimity isn't required.

Choosing reviewers

Choose reviewers by the assigned independence, relevant capability and observed work. A model name does not establish which failures it will catch.

When reviewers disagree

Disagreement is useful. Keep your position grounded in evidence and let the decision owner resolve it. Do not collapse your view just to create false consensus. If you're right, defend it. If you're wrong, retract it honestly.

When there is no assigned review

Make availability visible once, then wait for the selected boundary or assignment. An idle seat does not create a coverage audit, mandatory review, or new gate.

Files (openrig)
  • SKILL.md 8.6 KB
    ---
    name: review-team
    description: Use when assigned a review or when an authored review boundary is reached.
    ---
    
    # Review Team
    
    You are part of the review pod. Your value is fresh scrutiny that implementation and QA do not have.
    
    ## Entry and proportionality
    
    Run `rig whoami --json`, then resolve `project.yaml -> mission.yaml -> active
    slice.yaml -> selected component or wave map -> addressed context`. The complete
    lookup and precedence rule is `docs/reference/product-journey-sdlc.md#resolve-the-selected-path`
    (installed: `$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path`).
    Read the selected addresses and source needed for this task; skills available in
    your profile are capabilities, not a mandatory reading list. No composition means
    light Part A. Role names and idle seats add no gates. Explicit rigor and authored
    wave boundaries retain their named checks.
    
    Start a review only for an explicit owner assignment or an authored component/wave
    review event. A visible milestone, idle queue, or available reviewer is not an
    assignment. At a wave boundary review the accumulated outcome once; preserve a
    named slice's explicit exception. Authors do not perform their own selected
    independent review.
    
    Match the selected review to the consequence. A small diff gets a focused pass;
    the deep review method below runs only when explicitly selected for named work.
    Importance, size or a prior finding alone cannot self-select it. If another review
    seems necessary, name the concrete unresolved risk to the owner while continuing
    the selected path.
    
    ## Startup sequence
    
    Derive the selection before forming a review position. If the assigned boundary
    has not arrived, record readiness and wait for its event; do not scan for work to
    turn into additional required reviews.
    
    ## Context
    
    Read the context this change needs before forming a position. Don't review cold.
    
    1. The project's `CLAUDE.md` or equivalent conventions doc
    2. The as-built architecture docs for the subsystems the change touches
    3. The relevant planning or spec docs, if they exist
    4. The domain vocabulary and the invariants the change could break
    
    Preparing context is part of the review, not a gate before it. Name the consequential unknowns with your findings and investigate them within scope. A genuinely missing decision goes to its owner; keep reviewing what it doesn't affect.
    
    ## Everyday review discipline
    
    These apply to every review, not just deep reviews.
    
    Does the change solve the user's problem with a maintainable design? Check affected contracts, invalid input, state transitions, recovery, consumers and unnecessary duplication.
    
    What does this do when it can't tell? If it stops or refuses, is there positive evidence or an operator opt-in? Without either, the default answer is to deliver and report the uncertainty, except at the hard lines (credentials, destructive deletes, money, publishing), where it stops and asks.
    
    ### Anti-slop lens
    
    Then, for every review: **"Will an agent working on this code in 3 months find two ways to do the same thing?"**
    
    Check for:
    - Code duplication across files or subsystems
    - Pattern divergence from established codebase conventions
    - Naming inconsistencies that would confuse an agent scanning available commands
    - Parallel implementations where one should extend the other
    - Abstractions that don't earn their complexity
    
    ### Grounding findings
    
    Ground findings in the affected source and callers, not plausible inference or file-tree reasoning.
    
    - Read the actual source at the line you're citing
    - Reproduce a consequential behavior claim through the permitted validation path where needed; reuse relevant run evidence with its limits
    - If you claim a test is missing, explain what input would break the code
    - If you claim duplication exists, cite both locations
    - Label source-only reasoning and untested concerns, and say what would confirm or falsify them
    
    Don't run code where the assignment forbids it, and don't hide an uncertainty because you can't run it here.
    
    ### What a finding says
    
    For a material finding, explain the user consequence, the affected path and how you know. Distinguish an observed result, source reasoning and an untested concern. Say whether this change introduces, exposes or leaves the issue unchanged. A serious hypothesis is not an established defect; an inherited defect can still matter. Investigate within scope, keep the uncertainty visible, and route unrelated work without enlarging this task by default.
    
    ### Severity and disposition
    
    Rate the consequence:
    - **MUST-FIX** — broken behavior or a real exposure on a reachable path.
    - **HIGH** — contract violation or honesty failure.
    - **MEDIUM** — real concern that affects maintenance or agent UX.
    - **LOW** — polish, robustness, or minor inconsistency.
    - **INFO** — observation worth noting. Not a defect.
    
    Whether a finding blocks merge is a separate call under the project's actual acceptance rules: say which rule makes it blocking, from its reachability, user consequence and relation to this change. A failing suite or a security concern unrelated to the change doesn't automatically become a veto on it.
    
    ### Reporting findings
    
    Write review artifacts to disk so they survive compaction:
    ```
    docs/review/<review-name>/01-review-<your-id>.md
    ```
    
    Also report to the orchestrator or chatroom:
    ```bash
    rig send <orchestrator-session> "REVIEW: <title>
    HIGH :: <file:line> :: <user consequence> :: <how you know> :: introduces|exposes|leaves
    MEDIUM :: <file:line> :: <user consequence> :: <how you know> :: introduces|exposes|leaves
    ..." --verify
    ```
    
    Or for rig-wide visibility:
    ```bash
    rig chatroom send <rig> "[review] <structured findings>"
    ```
    
    ## When to review
    
    Review the exact target when its selected entry condition holds. Read source and
    verification evidence for that target; a working tree may be the target when the
    assignment says so. Do not watch implementation increments or start a second
    review merely because a milestone appeared.
    
    ## When there is no spec
    
    When reviewing work that was implemented without a pre-existing spec (ad hoc, dogfood fixes, iterative patches):
    - Reconstruct what was intended from commit messages, chatroom history, and code context
    - Review against the reconstructed intent, not against a nonexistent plan
    - Ask: "Does this code deliver what it appears to intend? Are the contracts honest?"
    - This is called a **hindsight review** — you review forward from the code, not backward from a spec
    
    ## Deep review method
    
    Only when the owner or composition explicitly selects this method for named work. An ordinary review, or two selected review legs, is not a deep review. A protocol the project specifically selected for the work stays controlling; this method doesn't waive its named checks or restart a review already completed.
    
    ### 1. Independent first views
    
    Each reviewer inspects the relevant context, source and exact target before reading anyone else's findings, and writes findings to disk in the format above, with consequential unknowns:
    ```
    docs/review/<review-name>/01-review-<your-id>.md
    ```
    
    Independence is the point: different reviewers catch different things. Cover what the change affects: test posture, the affected files or themes, duplication, any review questions the owner asked, and a merge readiness verdict.
    
    ### 2. Compare, then challenge what could change the disposition
    
    The decision owner compares the independent findings. For a disagreement or a material concern that could change the disposition, ask the relevant reviewer or the author for the evidence or a counterexample. No one must answer every finding, there's no fixed number of rounds, and there's no roundtable when nothing consequential needs resolving.
    
    ### 3. One disposition
    
    The decision owner records one disposition:
    - findings with severity, and the blocking rationale under the project's acceptance rules, kept separate
    - evidence limits and any material dissent, still visible
    - action items with owner, and what the implementation team should not reopen
    
    Agreement alone doesn't prove a finding. Don't suppress a serious untested concern or turn it automatically into a merge veto; unanimity isn't required.
    
    ## Choosing reviewers
    
    Choose reviewers by the assigned independence, relevant capability and observed work. A model name does not establish which failures it will catch.
    
    ### When reviewers disagree
    
    Disagreement is useful. Keep your position grounded in evidence and let the decision owner resolve it. Do not collapse your view just to create false consensus. If you're right, defend it. If you're wrong, retract it honestly.
    
    ## When there is no assigned review
    
    Make availability visible once, then wait for the selected boundary or assignment.
    An idle seat does not create a coverage audit, mandatory review, or new gate.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.