rule-trace
Rule Trace
Rules loaded into an agent are loaded context, not applied context — a rule that was followed looks identical to one that was ignored. This skill closes that gap. Every rule gets a stable ID anchored at a markdown heading; an agent that does real work appends a trace block disclosing which in-scope rules it considered (candidates) versus which it actually let constrain the work (applied); a catalog indexes every ID; deterministic scripts validate the system and count candidate-vs-applied usage across sessions so dead and miscoped rules become visible.
The most valuable signal is the diff between candidates and applied — a rule that is always a candidate but never applied is noise, miscoped, or being ignored.
Pick a mode
Read the user's intent and route to one mode. Each links the reference you should read before acting.
| Intent | Mode | Read first |
|---|---|---|
| Add rule tracing to a repo that has none | init | references/convention.md, references/importer-wiring.md |
| Convert existing/scattered rules into the traceable format | migrate | references/migration-guide.md, references/rule-anatomy.md |
| Maintain/clean an existing rule set, using usage data as evidence | audit | references/catalog-format.md, plus the report (below) |
| Count usage and build the dashboard | report | this file's "Counters" section |
The deterministic scripts live in scripts/ and are portable (Node ≥ 18, no dependencies). They resolve repo layout from an optional .agents/rule-trace.config.json (see references/catalog-format.md), falling back to the conventional layout. Run them from the target repo root, or pass --root <dir>.