Rules Doctor
Rules Doctor checks every rule, AGENTS.md file and .ingot config file in your project for conflicts, dead globs, duplicates, oversized rules and schema mistakes, and shows what each rule costs in tokens against your always-on budget. Run it in the IDE, where findings land in the Problems view, or from the terminal with ingot doctor.
Run it in the IDE
Rules Doctor runs on its own when a project opens and again whenever a rule, AGENTS.md or .ingot file changes, or files are added or removed. To run it by hand:
- Find Action (⌘⇧A / Ctrl+Shift+A) › Run Rules Doctor
- or press ⌘⌥⇧D (Ctrl+Alt+Shift+D)
Findings appear in the Problems view under the source Rules Doctor (schema mistakes under Ingot schema), and a notification sums them up, for example Rules Doctor: 1 error, 4 warnings, 2 info · 11 rule files · always-on 40 / 4k tokens. Double-click a finding to open the rule at the offending line or glob.
What it checks
| Finding | Severity | What it means |
|---|---|---|
| Conflict | warning | Two rules that load together ask for opposite things: tabs and spaces, single and double quotes, named and default exports, npm and pnpm, and similar |
| Override | info | A rule in a deeper folder contradicts a root rule for files under that folder (expected in monorepos, listed so you can see it) |
| Dead glob | warning | A globs pattern matches no file in the project, so that part of the rule never loads |
| Duplicate | warning | A rule repeats another rule word for word |
| Duplicate line | info | A sentence appears in more than one rule |
| Shadowed | warning | A rule never loads because another rule with the same name wins (for example .ingot/rules/style.md over .cursor/rules/style.mdc) |
| Oversized | warning | One rule is above the per-rule limit (1,500 tokens by default) |
| Over budget | warning | The rules that load in every turn for a folder are above the always-on budget (4,000 tokens by default) |
| Empty | warning | A rule has no instructions |
| Manual only | info | A rule has alwaysApply: false and no globs or description, so it only loads when you @-mention it |
| Schema | error or warning | A .ingot file breaks its schema: an unknown key (with the closest valid key suggested), a missing required value, a wrong type |
Token cost and the always-on budget
Every rule gets a token estimate (about 4 characters per token, the same estimate the agent's usage meter uses). Rules that load in every turn — alwaysApply: true rules and AGENTS.md files — count toward the always-on budget of each folder, so a monorepo package with its own rules gets its own line. Rules with globs, descriptions or manual rules only cost tokens in turns where they load.
Configure it
Put project defaults in .ingot/doctor.json (the file has a schema, so you get completion and validation while editing it):
{
"budget": 6000,
"maxRuleTokens": 2000,
"ignore": ["duplicate-line", "manual-only"]
}
ignore takes finding codes: conflict, override, dead-glob, duplicate, duplicate-line, shadowed, oversized, budget, empty, manual-only, schema.
Run it from the terminal
The ingot CLI runs the same checks, so you can gate rule changes in CI:
ingot doctor # readable report; exits 1 when there are errors
ingot doctor --strict # also exits 1 on warnings
ingot doctor --json # the full report as JSON
ingot doctor --budget 6000 --max-rule-tokens 2000 --ignore duplicate-line,manual-only
ingot doctor --no-global # leave out your own ~/.ingot rules
Flags win over .ingot/doctor.json. Your global rules in ~/.ingot are included by default, because they load in every project; pass --no-global in CI.
Related
- Rules and /init & AGENTS.md: how rules load
- Rule hits & provenance: which rules a turn actually loaded
- Effective rules: the merged rules for one file in a monorepo
- .ingot schemas & glob preview: completion and live validation while you edit