Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt

Use this file to discover all available pages before exploring further.

Extend Macroscope’s default correctness check with context to improve precision and avoid false positives. Custom correctness instructions teach our core code review what’s idiomatic, intentional, or off-limits in your codebase, so it flags real issues and stays quiet on patterns it would otherwise misread. Drop markdown files into .macroscope/correctness/, optionally scope them with glob patterns, and your team’s domain knowledge is folded into the same correctness review you already get.

​
File layout

Create one or more markdown files inside .macroscope/correctness/ at the root of your repo: 
.macroscope/
└── correctness/
    ├── configuration-principles.md
    ├── transaction-invariants.md
    └── auth-propagation.md

​
Front matter

Custom correctness instruction files support YAML front matter with the following fields:
FieldTypeDescription
includestring[]Glob patterns matching files these instructions apply to. If omitted, the instructions apply to all files reviewed.
excludestring[]Glob patterns matching files these instructions should not apply to. Evaluated after include.
If both include and exclude are omitted, the instructions apply globally to every file Macroscope reviews in the repo.

​
Example

.macroscope/correctness/configuration-principles.md: 
---
include:
  - "**/*.go"
  - "**/config/**"
exclude:
  - "**/*_test.go"
  - "**/testdata/**"
---

**Configuration principles.** Configuration must be explicit. No empty-string-means-default. No silent fallbacks. If a required value is missing, fail fast and loud at startup — not silently at runtime with an infinite hang or mysterious behavior. One source of truth for each config value, threaded through explicitly. Misconfiguration is a bug, and bugs must be caught as early as possible.

**No backwards compatibility.** This product is pre-release and in active development, never require dual-support, deprecation warnings, migration code, proto reservations or fallback paths. When something changes, change it everywhere. Break the old way. Delete the old code. Build forward.
In this example, the rules apply to all Go files and anything under a config/ directory, but skip tests and test fixtures. When Macroscope reviews a change that touches a matching file, these principles are folded into the correctness review automatically.
Front matter is optional. A correctness instruction file with no front matter applies to every file in the repo.

​
How matching works

For each file changed in a pull request, Macroscope walks .macroscope/correctness/ and includes the contents of every instruction file whose include/exclude patterns match that file’s path. Multiple instruction files can apply to the same file — they stack. If no instruction file matches, the correctness review behaves exactly as it does for repos without custom instructions.