Custom instructions

Add Markdown files under .macroscope/correctness/ to tell the built-in Correctness check about your codebase: intentional patterns, conventions, and constraints that would otherwise lead to incorrect or unwanted comments. These instructions have no separate agent charge. Custom instructions shape what Correctness reports. They don’t add new checks. Correctness still looks for general bugs and won’t reliably flag a violation that only your instructions describe. To catch bugs that depend on a rule or invariant specific to your codebase, use a Check Run Agent.

Instructions or a Check Run Agent?

You want to…	Use
Stop comments on code that is intentional, such as a deliberately reused idempotency key	Custom instructions
Explain conventions, framework behavior, or ownership so Correctness reads code correctly	Custom instructions
Catch every violation of a codebase-specific invariant, such as “soft-delete models must use a manager that filters deleted rows”	Check Run Agent
Enforce a policy with its own pass or fail result	Check Run Agent

Example

.macroscope/correctness/payments.md:

---
include:
  - "services/payments/**/*.go"
exclude:
  - "**/*_test.go"
---

Retries reuse the original idempotency key. Do not flag this reuse as a bug.

`ledger.Write` opens its own transaction when none is active, so callers
outside a transaction are expected.

Name the specific patterns not to report, and use include to scope them. Broad guidance such as “only flag bugs that would break production” or “ignore minor issues” can suppress many valid findings.

File layout

Every .md file under .macroscope/correctness/ is read recursively, except README.md. Directory nesting does not scope instructions; use front matter. Configuration comes from the latest PR commit. An edit takes effect on that PR immediately; other PRs need to include the commit. External forks use the default branch.

Front matter

Field	Default	Effect
`include`	All reviewed files	Apply these instructions to paths matching at least one glob.
`exclude`	None	Remove matching paths from this instruction’s scope.

Front matter is optional. All matching instruction files apply together. exclude removes paths from this instruction’s scope; it does not exclude them from correctness review. Use ignore rules for that. An explicit include can also bring matching files into review despite ignore patterns, test detection, generated-code heuristics, or the configured file-size limit. The instruction’s exclude wins within that file; another instruction can still include the path. Binary files and per-file diffs over 5 MB remain excluded.

Prerequisite steps

Only .macroscope/correctness/correctness.md configures when the correctness check runs. It can also contain ordinary scoped instructions.

---
requires:
  - build
waitsFor:
  - integration-tests
waitsForDiscoveryTimeout: 2
waitsForTimeout: 20
---

This waits for both checks to finish, then reviews only if build passed. Integration test results do not gate the review.

Field	Default	Accepted values
`waitsFor`	None	Check names that must finish.
`requires`	None	Check names that must pass: `success`, `neutral`, or `skipped`.
`waitsForTimeout`	`20`	1–30 minutes for prerequisites to finish.
`waitsForDiscoveryTimeout`	`1`	1–30 minutes for prerequisites to appear, capped by the overall timeout.

Use check names from the PR’s Checks tab. At most 10 distinct names across both lists. Writing these fields in another instruction file produces a warning and has no effect. A missing or timed-out prerequisite skips correctness. A non-passing requires check also skips it before any review is billed. A skipped expected review prevents automatic approval by default; see Approvability’s correctness gate. Correctness refuses "*" and Macroscope check names to avoid dependency cycles. Wait for your own CI jobs instead.

Pricing

Code Review

Status

Integrations

Workspace

Resources

Instructions or a Check Run Agent?

Example

File layout

Front matter

Prerequisite steps

​Instructions or a Check Run Agent?

​Example

​File layout

​Front matter

​Prerequisite steps

Instructions or a Check Run Agent?

Example

File layout

Front matter

Prerequisite steps