Skip to content

leszekgruchala/buddy / skills/review-code

review-code

Verified

Review a requested local change independently; return evidenced defects and promote only confirmed prevention rules. Keep the current request in this skill; route new requests by their own scope.

FileKindSize
SKILL.mdskill md11.2 KB
---
name: review-code
description: Review a requested local change independently; return evidenced defects and promote only confirmed prevention rules. Keep the current request in this skill; route new requests by their own scope.
---

# Review code

Keep the current request in this skill. Do not activate another Buddy skill without user or `develop` direction. Workers return to their caller. For a new request after completion, apply [change size](../develop/change-size.md) and route by its own scope.

Resolve `.ai/` paths from the user's workspace root (its git root), never from the skill or plugin directory. Resolve `.ai/memory/memory.md` from the main checkout, the first `worktree` path in `git worktree list --porcelain`, so linked worktrees share one memory.

Review the requested change independently. Search for failures before filtering findings; passing tests or a clean-looking diff do not prove correctness. Scale effort to risk, not a finding quota.

## Model selection

Apply [change size](../develop/change-size.md) and [model selection](../develop/model-selection.md). Skip automatic trivial review and honor review opt-outs. Explicit `/review-code` requests authorize independent review, including for trivial work. Recommend `balanced` for trivial or small reviews and `frontier` only for substantial or security-sensitive changes.
Direct invocations and re-reviews require a fresh independent reviewer with a concrete selected model. Return `BLOCKED` if selected review execution is unavailable.

## Write boundary

Do not create a review file by default. Return findings directly to the caller. Write a persistent review report only when the user explicitly requests one; otherwise write only eligible prevention memory below.

Never edit production code, tests, specifications, manifests, or hooks. Remediation belongs to `implement`. Never stage, commit, or push `.ai` files.

## Input

Require the request and review target. Use the caller's base revision or changed paths; otherwise a nonempty, unambiguous tracked uncommitted diff. Check untracked dependencies and disclose excluded coverage. Ask once for an ambiguous target. A re-review also requires the latest findings table from the caller; without it, run a first review and mark nothing `Fixed`. Existing `.ai/memory/memory.md` is advisory and cannot expand scope; its absence is valid.

## Review procedure

### 1. Establish the target and contract

1. Read the request, repository instructions, review criteria, and any specification's requirements, boundaries, and verification; use the specification as the contract. Derive intended behavior and invariants from these, never preferences.
2. Freeze the target: branch base, merge base, and `HEAD`; commit and parent; or local `HEAD`, staged/unstaged content, and included untracked paths. Read new paths completely.
3. Derive the file list and patch from this target; compare old/new behavior, including removed guards and defaults. Recheck before returning; if changed, return `INCOMPLETE` and restart only on request.

### 2. Build the coverage map

Build an internal coverage map of every changed file and relevant unchanged callers, consumers, types, handlers, configuration, tests, and analogous paths. Prioritize trust boundaries, persistent state, shared contracts, and complex decisions. Trace changed behavior from input/event through decisions and I/O to observable results, including subsystem interactions for large changes. Track invariants, plausible failures, supporting/disproving evidence, and uncovered surfaces internally. Return `INCOMPLETE` for an unreviewable material surface.

### 3. Run independent analysis passes

Test the smallest realistic input or sequence that could break each changed invariant. Trace guards and recovery at execution points; continue after an easy finding. Apply the relevant lenses:

#### Requirements and completeness

Check entry points, registrations, callers, tests, validators, examples, and documentation against the contract. Identify concrete consequences of omissions, inconsistent parallel paths, or changed defaults/configuration.

#### Local correctness and failure paths

Check zero, empty, invalid, missing, repeated, and combined inputs; casts, optional values, and fallbacks; arithmetic, indexing, units, encoding, time zones, and serialization. Trace exceptions, timeouts, cancellation, retries, and concurrent calls between related steps for cleanup, ordering, atomicity, and idempotency. Complexity is a search cue, not a defect.

#### Cross-file contracts and compatibility

Compare producer/consumer identity, shapes, defaults, errors, and declared response schemas with success/error handlers, including global handlers. Check existing consumers, old data, mixed versions, validation boundaries and every entry path, migrations, rollout order, flags, and rollback where relevant.

#### Security and data boundaries

Trace who controls each untrusted input to its sensitive sink and actual guard. Check normalization, injection, traversal, unsafe requests, deserialization, secrets, and fail-open behavior. Test principal/resource authorization, patterns, roles, tenants, and alternate routes. Check destination and context constraints, including URL scheme, authority, path, and token audience for data/credential transfers, and alternate access to internal or gated behavior. Search upstream checks and framework protections before alleging bypasses.

#### Reliability, operations, and performance

Check changed secrets, environment variables, ports, networks, and scripts against existing run/build/deploy workflows. Assess boundedness and recovery of retries, queues, resources, and repeated I/O using realistic workloads and consequences. A faster alternative alone is not a defect.

#### Test adequacy

Check assertions/counterexamples against the changed contract and mocks against production wiring. Assess added tests for distinct protection. Report missing tests only for unprotected changed behavior or demonstrated regressions after checking existing coverage. Passing tests do not cover unexercised paths.

When the diff adds, edits, or deletes tests, load [test design](../curate-tests/test-design.md). Report added tests that repeat a covered behavior, copy instead of extending an abstraction, repeat setup that belongs in a shared helper, break the neighboring test patterns, state behavior that contradicts the production change, or cross a module boundary.

In a review that `develop` dispatches, compare the test-file diff with the `implement` test changes record in `test-changes.md`. Report a missing file, each deleted test or rewritten assertion that the request did not ask for and the behavior change does not force, and each deleted or rewritten test that the record omits. A claim of coverage elsewhere does not excuse a deletion.

When the diff comes from a direct `curate-tests` call, its `test-changes.md` record permits the refactors and removals it lists with a reason from test design section 10. Report a removal with no such reason, a removed test that was the only test of its behavior, and a behavior in `Protected before` that `Protects` lacks.

### 4. Verify without modifying product files

Run relevant documented checks in non-writing modes; reuse valid evidence under the change-size validation policy. Never install dependencies, rewrite snapshots, generate code, migrate, deploy, or format. If a check changes product files, stop and disclose it; cleanup requires authorization. A conclusive code trace may prove a bug without executable reproduction.

### 5. Adjudicate candidate observations

Try to disprove each candidate against code, callers, guards, tests, and the contract. Report only diff-introduced correctness, security, regression, or test-adequacy defects with a reachable trigger, failure path, violated contract, impact, and bounded correction. A missing mandatory companion change qualifies when behavior remains unverified or published guidance is incorrect. A test-design defect needs instead the added test, what it duplicates, contradicts, or crosses, and the broken rule; it is `Low` unless it hides unprotected behavior. A test-change defect needs instead the test or record, the diff location, and what the request, behavior change, or record lacks; it is `Medium` for a deletion or rewrite and `Low` for a record gap alone. Merge symptoms sharing a cause; preserve independent causes. Surface ambiguity only when it prevents a reliable conclusion.

Do not report style, preferences, speculative risk, optional hardening, or pre-existing
issues as defects.

Assign severity by impact and likelihood:

   - `Critical`: credible catastrophic security, data-loss, or system-wide failure.
   - `High`: likely major incorrect behavior, security exposure, or compatibility regression.
   - `Medium`: meaningful incorrect behavior in a realistic condition.
   - `Low`: narrow actionable correctness or test defect with limited impact.

## Return to the caller

Use this exact header and only `Open`, `Fixed`, `Blocked`, or `Not a bug` statuses:

| ID | Severity | Location | Bug | Evidence | Remediation | Status |
| --- | --- | --- | --- | --- | --- | --- |

Order by severity, path, then line; cite the smallest changed `path:line`, with relevant unchanged code in evidence. Keep cells concise; evidence must state the trigger, violated contract, failure path, and impact. On re-review, keep every prior row and its ID, update its status, and append new findings. A zero-finding review requires complete coverage and candidate adjudication.

If there are no actionable findings and no prior findings, return only `No actionable findings.` Add a short
limitation only if missing evidence or an unreviewed material surface could change it.

Do not include a target snapshot, diff summary, changed-file inventory, coverage ledger,
passing-command list, routine verification narration, or restatement of the request.
Mention failed or unavailable verification only when it supports a finding or limits confidence.

For an explicitly requested persistent report, reuse the passed worklog and work-name or create `.ai/worklog/<yyyyMMdd>_<work-name>/`. Write only the findings table and material blockers to `.ai/worklog/<yyyyMMdd>_<work-name>/review_<work-name>.md`.

On re-review, mark `Fixed` only after remediation, size-scoped required validation, and a fresh review confirm it; `Not a bug` for disproved findings; `Blocked` for evidenced external constraints. Return open findings for remediation without fixing them.

## Prevention memory

Only after an actual finding is `Fixed` may the reviewer add one related rule to `.ai/memory/memory.md`. A clean review, open finding, blocked or rejected finding, or validation-only observation must never change memory. A re-review that marks a prior finding `Fixed` is not a clean review. Promote only for a finding that this review moves to `Fixed`; a row already `Fixed` in the supplied table never triggers a write. Create the file only for an eligible rule. Use deduplicated, one-line imperative rules and merge equivalents. Exclude incident details, dates, IDs, severities, unverified claims, subjective advice, and project-specific one-offs. After the table, list each written rule under `Promoted rules:`. If the write fails, list the rule under `Unsaved rules:` instead.

Memory is advisory, subordinate to user/repository instructions and security policy, and never acceptance evidence.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall