trigger-tree

> **Gate documentation discovery in CI. Measure whether your project instructions change what agents do.**
Two concrete offers:
1. **CI gate — immediate.** A deterministic, telemetry-free structural check fails a
PR with the affected file and a suggested fix.
2. **Instruction adherence — after a few working sessions.** See whether an applicable
CLAUDE.md directive was followed by observable behavior, and what that always-loaded
instruction costs on every request.
Heat maps and the A–F documentation-health grade add longer-term discovery evidence.
Everything runs locally with Python’s standard library: no cloud, analytics, network
calls, or model tokens while measuring.
Gate your CI on discoverability
The gate scores repository structure only — router coverage, orphaned docs, folder
entry points, and watch scope — so it works on day one without telemetry.
Commit a baseline once with tt gate --update-baseline. A regression then fails the PR
with the exact file and fix. SARIF and GitLab Code Quality exports are available in
examples/. The gate checks wiring, not wording; see CI gate.
Does your CLAUDE.md actually work?
Injected instructions are always loaded, so another read counter cannot answer this.
trigger-tree asks a narrower, measurable question: **when a directive applied, did its
declared probe observe the behavior it requested?**
| Directive | Opportunities | Followed | Rate | Confidence |
|---|---:|---:|---:|---|
| Route telemetry questions to docs/heat-model.md | 8 | 7 | 88% | warming |
| Run checks before committing | 6 | 5 | 83% | warming |
| Preserve stdlib-only runtime code | — | — | — | unobservable |
> Your always-loaded context is ~190 tokens per session. 2 directives (~34 tokens)
> have not been triggered in 12 sessions over 9.8 days.
The table is representative output. A committed, reviewable manifest defines each
probe; the model may propose it once, but you confirm it and deterministic local code
does every count thereafter. **Unobserved means evidence was not captured; it does not
mean violated.** Zero opportunities is never-triggered, a review prompt rather than
a removal recommendation — and only over sessions where that probe's capture was
actually running. Unobservable directives are split by cause: a rule with no
objectively testable condition is probably not firing for the model either, which is
advice you can act on, while a rule that needs the diff is simply outside what the event
stream can see. See instruction adherence.
Subagent personas are measured the same way. Every definition under .claude/agents/
puts its name and description in the system prompt on every request, and its body only
when the agent runs, so the two are counted separately. A persona you never invoke is
recurring cost in exactly the way an untriggered rule is. /tt insights reports which
personas ran, how often, and which have never been invoked. Opt in with /tt setup; only
the persona name is recorded, never the task given to it. A persona is only called
never-invoked over sessions where that capture was running.
Honest time to value
| Capability | When it becomes useful |
|---|---|
| CI discoverability gate | Immediately; no telemetry required |
| Instruction adherence | After at least 5 applicable opportunities, usually a few working sessions; earlier rates are provisional |
| Heat and documentation health | Directional during warm-up; strongest after roughly a month of normal work |