Agent Rules Pack

--- name: code-review description: Reviews a change set (the current branch, a pull request or uncommitted work) against a fixed checklist covering correctness, tests, security, data safety, performance and readability, and reports findings ranked by severity with file and line references. Use when asked to review code, check a PR or diff before merging, or look over changes before they are committed. Not for reviewing a whole codebase or for style-only formatting. ---

Code review

Review the change, not the whole codebase. The goal is to find the problems that would hurt after merge: wrong behaviour, missing tests, security holes, data loss and code the next person cannot maintain. Style preferences that a formatter or linter would catch are the lowest priority.

1. Establish the scope

1. Work out what is being reviewed. In order of preference: the pull request or branch the user named, the current branch compared with its base, or uncommitted changes.
2. List the changed files with line counts:

   node scripts/changed-files.mjs [base-branch]

The path is relative to this skill's folder. With no argument the script compares against origin/HEAD, then main, then master, and includes staged and unstaged work. If the script cannot run, use git diff --stat <base>...HEAD and git status --short.

1. Read the description of the change: the PR text, linked issue, commit messages. Write down in one sentence what the change is meant to do. Every finding is judged against that intent.
2. If the change is larger than about 800 changed lines, say so in the report and suggest how it could have been split. Still review it, starting with the riskiest files: data access, auth, migrations, public interfaces, then everything else.

2. Read in the right order

1. Tests first, if any. They show what the author believes the code does.
2. Interfaces next: public functions, API routes, schemas, types, configuration.
3. Implementation last, following the data from input to output.
4. Open the surrounding code for every non-trivial hunk. A diff without context hides callers that now break.

3. Apply the checklist

Use checklist.md. For each item, either note a finding or move on. Do not report items that pass.

The checklist covers, in priority order:

1. Correctness: logic, edge cases (empty, null, zero, one, many, very large), error handling, concurrency, time zones and off-by-one errors.
2. Data safety: migrations, deletes, irreversible writes, backfills, transactions.
3. Security: input validation, injection, authorisation on every new entry point, secrets, logging of sensitive data.
4. Tests: does a test fail if the new behaviour breaks? Are the edge cases from step 1 covered?
5. Interfaces and compatibility: breaking changes to APIs, events, database columns, environment variables, CLI flags.
6. Performance: queries in loops, unbounded lists, missing pagination, work on the hot path.
7. Readability and maintenance: naming, dead code, duplication, comments that explain why.

4. Verify before you claim

• Run the project's test, lint and type-check commands if they exist and are safe to run. Record which ones you ran and the result.
• Before reporting a bug, trace it far enough to be confident. If you are not sure, label it as a question, not a defect.
• Do not invent APIs or library behaviour. If a finding depends on how a dependency behaves, check its source or documentation in the repository.

5. Report

Use this format. Keep each finding to what the author needs to act on it.

## Review: [one-sentence summary of what the change does]

Scope: [branch or PR], [N] files, +[added] / -[removed]
Checks run: [test command: pass/fail], [lint: pass/fail], [type check: pass/fail]

### Blocking
1. [file:line] [Problem in one sentence.]
   Why it matters: [consequence].
   Suggested fix: [specific change].

### Should fix
1. [file:line] ...

### Questions
1. [file:line] [What is unclear, and what answer would resolve it.]

### Minor
- [file:line] [one line each]

Verdict: [Approve / Approve with changes / Request changes]

Severity rules:

• Blocking: wrong behaviour, data loss, security hole, missing authorisation, a breaking change without a migration path, or tests that do not test the change.
• Should fix: likely bugs in edge cases, missing tests for important paths, performance problems that will show at expected load.
• Questions: anything you could not confirm.
• Minor: naming, small duplication, comments. Cap at ten items.

If there are no blocking or should-fix findings, say so plainly and approve. Do not pad the report.

Rules

• Never change code during a review unless the user asks you to fix the findings.
• Never approve a change whose tests you could not run without saying that you could not run them.
• Quote file paths and line numbers exactly as they appear in the diff.
• Be direct and specific. Criticise the code, not the author.

Agent instructions: [Project name]

These instructions apply to every coding agent working in this repository. Replace anything in [square brackets], and delete lines that do not apply.

Project

• [One or two sentences: what this project is, who uses it, and what matters most, for example correctness of billing data or uptime.]
• Main language and framework: [e.g. TypeScript with Next.js, Python with Django].
• Layout: [src/ application code, tests/ tests, scripts/ maintenance scripts, docs/ documentation].
• Where to look first: [entry point, main module or architecture document].

Commands

| Task | Command |
|---|---|
| Install dependencies | `[install command]` |
| Run locally | `[dev command]` |
| Format | `[format command]` |
| Lint | `[lint command]` |
| Type check | `[type check command, or delete this row]` |
| Run all tests | `[test command]` |
| Run one test file | `[single test command]` |
| Build | `[build command, or delete this row]` |

Use the project's package manager and scripts. Do not switch package managers or add new tooling.

Code conventions

• Follow the formatter and linter configuration in the repository. Do not change their settings.
• Names say what things are and do. Avoid abbreviations a new team member would have to guess.
• Functions do one thing. Return early instead of nesting deeply.
• Handle errors where you can act on them; otherwise let them propagate with context. Never swallow an exception silently.
• Comments explain why, not what. Remove commented-out code instead of leaving it.
• Keep public interfaces (APIs, exported functions, database columns, configuration keys, CLI flags) backwards compatible unless the task says otherwise.
• No new dependencies without asking. When one is approved, choose a maintained, widely used package and pin it through the package manager.

Testing

• New behaviour comes with tests. Bug fixes come with a test that fails without the fix.
• Follow the structure and helpers of the existing tests near the code you change.
• Tests must not depend on network access, the real clock, test order or shared state.
• Never delete, skip or weaken a test to make the suite pass. If a test is wrong, say so and explain.

Working style

• Read before you write. Look at the code around the change and follow the patterns it already uses, even where you would have chosen differently.
• Keep each change focused on the task. Do not rename, reformat or refactor unrelated code in the same change.
• Prefer editing existing files to creating new ones. Do not add documentation files unless asked.
• Ask before you start when the request is ambiguous, when the change would touch more than [10] files, or when it needs a new dependency.
• When you make an assumption, state it in your summary.

Security and secrets

• Never commit secrets, tokens, API keys, passwords, private keys or real customer data. Configuration comes from environment variables or the secret store. Keep .env files out of git and list variable names, without values, in .env.example.
• Never print secret values in output, logs, tests, fixtures or commit messages.
• Validate all external input at the boundary: requests, webhooks, files, queue messages, third-party API responses.
• Use parameterised queries. Never build SQL, shell commands or file paths from input by string concatenation.
• Do not send code or data to outside services unless the task requires it.

Never do without explicit approval in this conversation

• Run destructive commands: rm -rf, git reset --hard, git clean -fdx, git checkout -- . or git restore . over uncommitted work, dropping or truncating databases, deleting cloud resources.
• Force push (git push --force or --force-with-lease), rewrite published history, or delete remote branches or tags.
• Push directly to main, master or release branches, merge pull requests, publish packages or deploy.
• Run migrations or scripts against shared, staging or production databases.
• Change CI/CD pipelines, infrastructure, authentication or billing configuration.
• Disable or skip tests, lint rules, type checks or security controls to get a passing build.
• Install global tools, change system settings, or edit files outside this repository.

Git, commits and pull requests

• Branch names: type/short-description, for example fix/login-redirect or feat/csv-export.
• Commit messages follow Conventional Commits: type(scope): summary in the imperative mood, at most 72 characters. Types: feat, fix, docs, refactor, test, perf, build, ci, chore. Use the body to explain why. Mark breaking changes with ! after the type and a BREAKING CHANGE: footer.
• One logical change per commit. Keep formatting-only changes in their own commit.
• Create commits only when asked. Never commit generated build output, local configuration or editor files.
• Pull request descriptions cover: what changed and why, how it was tested, screenshots for UI changes, risks and how to roll back, and the linked issue.

Before you say done

1. Run the formatter, linter, type checker and tests listed under Commands. They must pass. If something fails and you cannot fix it, report exactly what fails and why.
2. Run the build if the project has one.
3. Read your own diff from top to bottom. Remove debug output, commented-out code, stray files and anything that looks like a secret.
4. For user-facing changes, check the result in the running app where you can.
5. Summarise: what changed and why, the files touched, the commands you ran with their results, what you could not verify, and any follow-up needed.

Never say that something works, passes or is fixed unless you ran it and saw the result.

Maintaining this file

Owner: [team or person]. Last reviewed: [YYYY-MM-DD]. Keep this file under about 200 lines. When an instruction stops being true, change it in the same pull request as the code.