code-review

Files (3)

• SKILL.md
• code-review-guide.md · references/
• report-schema.json · references/

SKILL.md (first lines)

# Code review agent

## When to use

- Reviewing diffs, commits, PRs, or changed files before merge.
- Auditing generated code or refactors for regressions.

## Goal

Conduct a defensive, evidence-based review of local repository changes.
Flag only material defects—incorrect behavior, data loss, security
vulnerabilities, or crashes. Return prioritized findings with exact code
citations and targeted remediation.

## Scope

**In scope**:

- Lines added or modified in the diff
- New public API contracts introduced by the diff
- Security and correctness of new logic

**Out of scope**:

- Unchanged code visible in context
- Architecture or design concerns
- Missing tests or test coverage
- Style, formatting, naming conventions
- `DRY` / abstraction suggestions
- Hypothetical callers or inputs (unless new public API)

## Input

Determine scope from the first available source:

- Files or folders provided by the user.
- Current changes in the repository: staged, `unstaged`, and `untracked`
  files in a versioned project.

Abort with a clear message if no scope detected.

Gather intent grounding matching the resolved scope:

- Commit or `PR` scope: the commit message(s) or `PR` title and
  description.
- Uncommitted-changes or file scope: comments near each changed `hunk`,
  plus any intent the requester stated when invoking the review.

## Workflow

1. **GATE**—Identify changed files and diff boundaries; abort if no
   scope. Delete `code-review-report.yaml` from the project root if
   present.
2. **ORIENT**—Read `references/code-review-guide.md` for categories,
   severity levels, decision rules, scope, and calibration. Read
   `references/report-schema.json` as the output contract. Anchor to
   review goal; name what the review won't change.
   - Ground runtime execution model (single-threaded CLI, async loop,
     multi-threaded server, isolated worker) and threat model. Limit
     validation to source inspection and isolated local checks; exclude
     live-system probing and exploit development.
   - Gather intent grounding (see Input) for the `hunks` under review
     before the category passes.
3. **ACT**—Execute:
   - Read relevant project documentation (`AGENTS.md`, `ORIENT.md`,
     `DESIGN.md`), nearby code, and tests for grounding.
   - Detect and run configured linters, type checkers, and static
     analysis; treat tool errors as confirmed findings.
   - Sweep up to `PHASE_CAP` (7) phases against a running ledger; stop
     the first phase that contributes zero new candidates:
     - Each phase scans every category below in full before consulting
       the ledger—produce the complete candidate list first, then
       dedupe. Skipping already-covered ground before scanning defeats
       the sweep.
     - Each phase carries a rotating heightened-focus category, cycling
       `((phase - 1) mod 8) + 1` through the category order below—
       rotation adds focus without narrowing scope; every phase still
       scans all 8.
     - Tag each candidate with a defect signature:
       `category:path:line-or-range:short-defect-slug`. Treat a
       candidate as new only when its signature stays absent from the
       ledger.
     - Append new candidates to the ledger after each phase.
   - Categories (every phase scans all):
     - **Correctness**: Logic, conditions, bounds, formulas, collection
       mutation.
     - **Null and type safety**: Null/undefined `dereferences`,
       unchecked Result/Option types, unsafe coercions.
     - **Concurrency**: Shared mutable state, lock release paths,
       `read-modify-write` atomicity, `async` race conditions.
     - **Security**: Injection, `hardcoded` credentials, auth bypass,
       `PII` in logs, unsafe `deserialization`, missing boundary
       validation.
     - **Resource management**: File, socket, connection, lock, or
       allocation without guaranteed release.
     - **Error handling**: Silently discarded errors, wrong return on
       error branch, `unpropagated` errors.
     - **API misuse**: Deprecated functions, wrong argument order,
       ignored return values, missing required options.
     - **Data integrity**: `Unvalidated` index/size/key inputs, broken
       serialization contracts, truncation risk.
4. **VERIFY**—Run once, after the phase sweep completes—never per phase.
   Prove each ledger finding against code, project mandates, and app
   threat model. Apply decision rules from the guide (resource leak,
   injection, null safety, concurrency, error handling, intent check).
   - Require a concrete trigger scenario, reachable code path, and
     material impact for each finding. Code evidence suffices; don't
     require exploit construction or live-system reproduction.
   - Drop speculative or out-of-scope findings from active `findings`.
   - Route findings lacking concrete trigger scenarios or carrying
     qualifying intent evidence to `suppressed_findings`; cite the
     missing scenario or intent evidence—never emit them in `findings`.
5. **PERSIST**—Skip only when both `findings` and `suppressed_findings`
   stay empty. Otherwise write `code-review-report.yaml` to the project
   root conforming to `references/report-schema.json`; omit the
   `suppressed_findings` key entirely when empty. Write once, after
   VERIFY passes. Use `|` block scalars for multi-line `suggestion` and
   `excerpt` fields.
6. **REPORT**—Sort findings by severity. Emit the result following the

From mystilleef/spae-framework, MIT.

More from mystilleef/spae-framework