Beta Coming soon. This feature is still being built, so names and details may change before it ships.

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

FindingSeverityWhat it means
ConflictwarningTwo rules that load together ask for opposite things: tabs and spaces, single and double quotes, named and default exports, npm and pnpm, and similar
OverrideinfoA rule in a deeper folder contradicts a root rule for files under that folder (expected in monorepos, listed so you can see it)
Dead globwarningA globs pattern matches no file in the project, so that part of the rule never loads
DuplicatewarningA rule repeats another rule word for word
Duplicate lineinfoA sentence appears in more than one rule
ShadowedwarningA rule never loads because another rule with the same name wins (for example .ingot/rules/style.md over .cursor/rules/style.mdc)
OversizedwarningOne rule is above the per-rule limit (1,500 tokens by default)
Over budgetwarningThe rules that load in every turn for a folder are above the always-on budget (4,000 tokens by default)
EmptywarningA rule has no instructions
Manual onlyinfoA rule has alwaysApply: false and no globs or description, so it only loads when you @-mention it
Schemaerror or warningA .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.