code-review

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Code Review

## Overview

Review local changes as a reviewer, not as an implementer. Prefer the smallest current review surface: local worktree changes first, then branch changes against a base branch only when the worktree has no tracked or untracked changes. When no base branch is named, use the Git Town parent branch before falling back to the default branch. Local worktree review includes staged tracked changes, unstaged tracked changes, and untracked files. Start with a local review pass, then use zero to three language/risk-specific subagents only when they are likely to improve review quality enough to justify the token cost. Do not run tests or linters unless the user explicitly changes the scope.

Invoking this skill is permission to use review subagents when useful; it is not a requirement to spawn them. A local-only review is valid for small, obvious, low-risk, or already well-tested diffs.

## Scope

Determine review depth from the request:

- Default to lightweight review.
- Switch to in-depth review when the user explicitly asks for deeper review.

Determine review range in this order:

1. Check local tracked and untracked changes:

```bash
git diff --cached -U10
git diff -U10
git diff --cached --name-only
git diff --name-only
git ls-files --others --exclude-standard
```

2. If any staged tracked, unstaged tracked, or untracked files exist, review all of them as `local changes`.
   - Include staged tracked changes from `git diff --cached -U10`.
   - Include unstaged tracked changes from `git diff -U10`.
   - Include untracked file contents by reading the files directly or producing a pseudo-diff against `/dev/null`.
   - Do not exclude untracked files just because they are not staged.
3. If there are no local tracked or untracked changes, review the current branch against the base branch named by the user.
4. If the user did not name a base branch, resolve the current branch's parent with Git Town:

```bash
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
BASE_BRANCH=$(git-town config get-parent "$CURRENT_BRANCH" 2>/dev/null || true)
```

5. If Git Town does not return a parent branch, fall back to `main`, then `origin/main`.

For branch review, compute:

```bash
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
BASE_BRANCH="${USER_BASE_BRANCH:-$(git-town config get-parent "$CURRENT_BRANCH" 2>/dev/null || true)}"
if [ -z "$BASE_BRANCH" ]; then
  BASE_BRANCH=main
fi
if ! git rev-parse --verify "$BASE_BRANCH" >/dev/null 2>&1 && git rev-parse --verify origin/main >/dev/null 2>&1; then
  BASE_BRANCH=origin/main
fi
BASE=$(git merge-base HEAD "$BASE_BRANCH")
git diff -U10 "$BASE"
git diff --name-only "$BASE"
```

If the named base, Git Town parent, and fallback default branches cannot be resolved, stop and ask for a valid base branch.

## Workflow

1. Check for staged tracked, unstaged tracked, and untracked files.
2. If any local changes exist, build the review packet from the staged diff, unstaged diff, and untracked file contents. Do not include branch commits in this mode.
3. If no local tracked or untracked changes exist, resolve the base branch from the user's request, or use `git-town config get-parent "$(git rev-parse --abbrev-ref HEAD)"` when no base is requested, then build the branch review diff from the merge base.
4. In local changes mode, list untracked files with `git ls-files --others --exclude-standard` and include their contents in the review packet.
5. Build a compact review scope:
   - review mode: `local changes` or `branch`
   - base branch and merge base, when in branch mode
   - inferred intent in one sentence
   - risk focus in one sentence
   - changed file list
   - untracked file list and confirmation that untracked file contents are included when in local changes mode
6. Do a local review pass first. Read surrounding files only where needed to understand behavior, contracts, and tests.
7. Decide whether subagents are worth it. Use zero to three reviewers based on the rubric below.
8. If using subagents, send each a narrow packet with only the files, diff excerpts, contract context, and risk lens it needs. Launch multiple selected reviewers in parallel, collect outputs, and close each subagent once its result is captured.
9. Validate or disprove returned findings against source before reporting.
10. Produce findings with high confidence only.

If subagents are unavailable, continue locally. Mention that only if it materially affects confidence or the user explicitly asked for subagents. For in-depth review, prefer more local source context before adding reviewers by default.

## Sub-Agent Selection

Use 0-3 reviewers total. Do not spawn reviewers merely because a language matches. Pick the smallest reviewer set that addresses real risk:

- `0` reviewers: docs-only changes, tiny diffs, mechanical renames, obvious follow-up fixes, generated updates, or low-risk code where the local pass gives high confidence.
- `1` reviewer: normal non-trivial code change with one dominant risk or one language/framework-specific concern.
- `2` reviewers: meaningful behavior change with two independent risk areas, such as Rust API shape plus tests, Vue reactivity plus accessibility, or public API contract plus security.
- `3` reviewers: large/cross-module diffs, auth/security/data mutation, external APIs, migrations, concurrency, or explicit deep/adversarial review.

Prefer a language-specific reviewer when language/framework details are the dominant risk. Prefer generic risk reviewers when correctness, security, contracts, reliability, or testing are more important than language mechanics.

Use these plugin agents when available from the `rolling-wave-engineering` plugin:

- `correctness-reviewer`: default for behavior-changing code, logic, state, and regression risk.
- `testing-reviewer`: default when behavior changes, tests changed, or coverage is uncertain.
- `maintainability-reviewer`: default for non-trivial code changes or existing-file complexity.
- `typescript-reviewer`: when files include `.ts`, `.tsx`, or TypeScript blocks in Vue SFCs.
- `vue-reviewer`: when files include `.vue`, Vue composables, Pinia stores, Vue Router, or Nuxt files.
- `rust-reviewer`: when files include `.rs`, `Cargo.toml`, `Cargo.lock`, `build.rs`, Rust FFI/bindgen code, unsafe Rust, async Rust, or concurrency-heavy Rust.
- `security-reviewer`: when changes touch auth, permissions, public endpoints, secrets, user input, rendering untrusted content, or URL handling.
- `api-contract-reviewer`: when changes touch API routes, request/response types, serializers, exported types, or public interfaces.
- `reliability-reviewer`: when changes touch retries, timeouts, async handlers, jobs, cleanup, lifecycle, or error handling.
- `adversarial-reviewer`: when the diff is large or touches high-risk areas such as auth, data mutation, external APIs, or cross-cutting state.

Use these document/spec reviewers only when reviewing rolling-wave docs, specs, plans, or slice artifacts rather than code:

- `coherence-reviewer`
- `scope-guardian-reviewer`
- `feasibility-reviewer`
- `spec-flow-analyzer`

Fallback split when plugin agents are unavailable:

- Correctness and regressions
- Contracts and data flow
- Coverage and operational risk

Each sub-agent should be told to report only high-confidence findings in its assigned lens and to skip style-only comments or speculative refactors. Keep prompts narrow; do not ask every reviewer to review the whole diff.

From rijkvanzanten/rolling-wave-engineering, MIT.

More from rijkvanzanten/rolling-wave-engineering