ADR-105: Progressive Disclosure for Way Trees¶
Summary¶
- Decided: A complex domain is written as a tree of ways rather than one large way. The root uses threshold 1.8 to catch broad mentions, middle ways 2.0, and leaves 2.5 for narrow topics. Sibling ways keep vocabulary overlap (Jaccard similarity) below 0.15, checked by
way-tree-analyze.sh. When a parent way has fired, its children's thresholds drop by 20%.show-way.shlogs each disclosure with its parent, depth and distance. High-stakes leaves carry a Common Rationalizations table. A way under 80 lines with one concern stays flat. - Trades away: Domains split into more files (docs went from one to four), authors have to learn the threshold and vocabulary conventions, and checking the parent marker adds about 0.1 ms per way in the scan loop. The record rejected loading through the Skill tool because it relies on the agent choosing to load, and rejected longer vocabularies because they increase overlap between ways.
- One-way? No. The record does not discuss reversal. The change is to file layout, thresholds and one marker check, and a tree can be merged back into a flat way.
- Probes: Not confident (hooks-over-skills): Should guidance load from hooks rather than from the agent choosing a skill? Yes or no. Not confident (parent-boost): Should a fired parent make its children easier to fire? Yes or no.
- Inversion: At one end a domain is one way that injects everything on one trigger. At the other, the agent loads each piece itself on demand. This decision sits between: hooks still decide what loads, and the tree lets them load only the branch the conversation reaches.
Context¶
As the ways corpus grows (48+ ways at time of writing), flat ways create two problems:
- Token bloat: A 173-line docs way dumps everything on a single trigger, regardless of whether the user needs README guidance, docstring conventions, or Mermaid styling.
- Vocabulary crowding: As more ways share overlapping vocabulary, BM25 discrimination degrades. A broad way with 20 vocabulary terms competes with everything.
Comparison with obra/superpowers revealed that their skill system uses lazy-loading via the Skill tool, while our hook-based system loads eagerly on match. We need an equivalent of lazy-loading within the hooks architecture.
The supply chain tree (softwaredev/code/supplychain/) already demonstrated the pattern organically — 11 files across 3 depth levels with threshold progression from 1.8 to 2.5 and zero vocabulary overlap between siblings.
Decision¶
Adopt tree-structured ways with threshold progression for complex domains. Specifically:
Threshold convention: Root ways use threshold 1.8 (broad catch), mid-tier 2.0 (focused), leaves 2.5 (narrow specialist). This ensures the root fires on general mentions and children only fire on specific sub-topics.
Vocabulary isolation: Sibling ways must have Jaccard similarity < 0.15. Each child owns its own keyword space. The way-tree-analyze.sh tool validates this at authoring time.
Parent-aware threshold lowering: When a parent way's marker exists, children's BM25 thresholds are reduced by 20%. This is evidence-based: if the parent domain is active, children should fire more easily.
Tree disclosure tracking: show-way.sh records disclosure events to a JSONL metrics file per session, capturing: parent way, depth, epoch distance from parent, and sibling coverage. This data feeds back into authoring decisions (never-fire children need vocabulary broadening).
Anti-rationalization patterns: High-stakes leaf ways include "Common Rationalizations" tables that counter the agent's tendency to skip steps. Placed in leaves (not roots) so they only appear when the agent is actively doing the thing it might skip.
Token budget targets: Realistic single path ~1200 tokens, worst-case full tree ~4000 tokens. Validated by /ways-tests budget.
When NOT to tree: Ways under 80 lines with a single cohesive concern stay flat (errors, performance, debugging, config, commits).
Consequences¶
Positive¶
- Token efficiency: typical session injects ~1200 tokens of relevant guidance instead of ~600 tokens of everything
- Matching precision: narrow child vocabularies reduce false positives and vocabulary crowding
- Anti-rationalization: high-stakes ways actively counter shortcuts the agent might take
- Observability: disclosure metrics reveal which children never fire (vocabulary gaps) and which cascade instantly (vocabulary overlap)
Negative¶
- More files to maintain (docs: 1→4, testing: 1→3, security: 1→4)
- Authors must understand threshold progression and vocabulary isolation conventions
- Parent-aware threshold lowering adds a marker check per way in the scan loop (~0.1ms each)
Neutral¶
- Think strategies (stateful cognitive scaffolding) follow the same pattern but with explicit stage advancement rather than independent child activation
- The
way-tree-analyze.shtool and/ways-tests tree|budget|crowding|metricscommands make tree health observable - Integration test accuracy improved from 87% to 94% after refactoring
Alternatives Considered¶
- Skill-based lazy loading (obra/superpowers approach): Skills load via the Skill tool on-demand. We considered this but it requires the agent to self-select, which is unreliable. Hook-based triggering is more deterministic.
- Flat ways with longer vocabulary: Keep single files but expand vocabulary to cover sub-topics. Rejected because it worsens vocabulary crowding — more terms per way means more overlap between ways.
- CLAUDE.md includes: Load sub-content via CLAUDE.md references. Rejected because it's spatial coupling (position in file) rather than temporal coupling (when the agent needs it).
Reference Implementation¶
hooks/ways/softwaredev/code/supplychain/ — 11 files, 3 depth levels, threshold 1.8→2.0→2.5, all sibling Jaccard < 0.06, worst-case ~3840 tokens, average path ~940 tokens.