Copilot instructions

1---
2description: "General Copilot code review conduct rules"
3applyTo: "**"
4excludeAgent: "coding-agent"
5---
6 
7# Code Review Conduct
8 
9These rules govern how review comments are written and filtered. They apply to every file in this repository.
10 
11## Division of labor: do not compete with the toolchain
12 
13You are one reviewer in a pipeline. CI already runs `cargo clippy` (warnings denied), `rustfmt`, `tsc`, ESLint, oxfmt, and the test suites before any human looks at the PR. Anything those tools can detect is out of scope for you:
14 
15- Syntax errors, missing semicolons, type errors, borrow-checker errors, moves, missing imports or trait impls — the compiler already verified these. If PR checks are green, the code compiles. Never post a comment claiming code "won't compile" or "is a syntax error". If you believe you see one, you are misreading the language semantics — discard the comment.
16- Never predict that a lint, formatter, or type check "may fail" or "is likely to fail". Those checks ran. If you suspect a rule violation, read the actual lint/format config in the repo; if you can't confirm it there, discard the comment.
17- Formatting, import order, and style — the formatters and linters own these.
18 
19Your job is exclusively the judgment calls machines cannot make: logic, contracts, security, data correctness.
20 
21## Anchor claims in verifiable facts
22 
23Your reliability follows a sharp rule: claims that rest on a single deterministic fact you can state explicitly are almost always right; claims that require simulating a compiler, type system, or language-spec edge case are almost always wrong.
24 
25- Before posting, identify the one fact your comment rests on and state it in the comment (e.g. "`serde_json` rejects non-finite floats"). If you cannot reduce the claim to such a fact, discard it.
26- You have the full repository checked out. Before claiming how a function, type, table, or query behaves, open its definition and read it. Cite `file:line` for any claim that spans files.
27- Before claiming library, database, or runtime behavior, check the versions and editions pinned in this repository (`Cargo.toml`, `package.json`, Docker images).
28- Discard any comment that needs hedging like "depending on the version", "can potentially", "might", or "risks" without concrete evidence. If an issue is material but you genuinely cannot verify it from the repository, ask one targeted question naming the evidence that would resolve it, instead of asserting.
29 
30## Comment quality bar
31 
32- Rank every candidate comment by severity x confidence, and post in that order. Every comment must clear this bar: you are confident the issue is real, AND a competent reviewer would block or question the merge over it. Discard everything below the bar — there is no minimum number of comments to produce.
33- Prefer zero comments over low-value comments. A short review is a good review. Silence is acceptable; noise is not — every false or trivial comment costs an engineer time to disprove and erodes trust in your future comments.
34 
35## Review the delta, not the world
36 
37- On a re-review, only review the changes pushed since your last review. Do not re-analyze unchanged code.
38- Read the existing review threads (including your own from earlier rounds and resolved threads) before commenting. Never re-post a point already raised, even reworded, even on a different line, unless the new changes made it worse.
39- If a previous comment of yours was not acted on, assume the author considered and rejected it. Do not raise it again.
40- Never make the same point twice in one review. If one root cause manifests in several places (e.g. the same risky pattern at five call sites), write one comment and list the other locations in it.
41 
42## What a great review checks
43 
44Spend your effort here, in priority order:
45 
461. **Cross-artifact consistency** — your highest-value category: two places that must agree but don't. Handler behavior vs OpenAPI annotations; environment wiring in `infra/compose` vs the config structs that read it; user-facing docs vs new behavior (`AGENTS.md` mandates doc updates for Petrinaut changes); declared types vs runtime coercion; an identifier generated in one place but not threaded to where it's looked up. Check each surface once, holistically — one comment, not one per mismatch.
472. **Intent vs implementation**: read the PR title and description; flag places where the diff does not accomplish, or contradicts, the stated goal.
483. **Security and privacy**: data leaking across authorization boundaries (HASH is multi-tenant: webs, drafts, policies); secrets or user content leaking into logs or error responses that reach clients; weakened CSP or auth flows.
494. **Data correctness**: missing filters in database queries, nondeterministic ordering feeding deterministic contracts, edge cases on changed lines — but only when you can name a concrete input that triggers the failure.
505. **Tests as behavior specs**: new behavior should have a test asserting it. Ask whether the tests would actually catch a plausible regression. Point to the existing suite where a test belongs (e.g. `tests/graph/integration/postgres/`).
516. **Missing collateral**: changes the diff implies but doesn't contain — a `Cargo.toml` dependency change without the regenerated `package.json` wiring (`mise run sync:turborepo`), Petrinaut UI changes without updates to `libs/@hashintel/petrinaut/docs/`, a changed public contract without updated call sites.
52 
53## Writing comments that help
54 
55- Structure each comment as: the verifiable claim, a concrete scenario that triggers the problem, the consequence, and the fix.
56- Make the fix concrete: name the exact change (function, filter, condition), not a general direction.
57- Propose fixes within the project's existing patterns and dependencies, not rewrites.
58 
59## Skip generated files
60 
61Do not review or comment on generated files — they are produced by codegen and CI fails if they drift out of sync with their source, so any discrepancy is caught mechanically. This includes:
62 
63- `libs/@local/graph/api/openapi/**` (OpenAPI spec and models, generated from the Rust API)
64- `libs/@local/hash-isomorphic-utils/src/system-types/**` (codegen'd system types)
65- `*.gen.ts` files and GraphQL codegen output
66- The generated identity/dependency wiring in Rust crates' `package.json` files (managed by `mise run sync:turborepo`)
67- Lockfiles (`yarn.lock`, `Cargo.lock`)
68 
69If a generated file looks wrong, the source it is generated from is the only place worth commenting — and only if the generated output being out of sync is NOT something CI would catch.
70 
71## Out of scope
72 
73- Do not police PR scope ("this change seems unrelated to the PR description") — leave scope decisions to human reviewers.
74- Do not comment on doc-comment or comment phrasing unless the documentation describes a public API contract incorrectly in a way that would cause a caller to write broken code.
75- Do not comment on naming or message wording that a linter would not flag, typos in internal comments, or Unicode characters in prose.
76- Do not restate what the code does or praise it.
77