review-agents-tree

review-agents-tree

Manual durable-context hygiene pass.

Not a workflow gate. Not a replacement for distill-knowledge.

Run this periodically to keep the tracked AGENTS.md tree lean, conflict-free, and aligned with current code/tests.

Read first

• ../references/persistent-artifacts-contract.md
• ../../references/communication-mode.md
• root tracked AGENTS.md
• all tracked local AGENTS.md files under the repository
• tracked AGENTS.override.md paths only to detect misuse or drift; never treat them as canonical repo truth
• relevant code/tests only when a guidance conflict or staleness finding needs verification

Scope

This skill owns:

• periodic best-practice audit of the tracked AGENTS.md tree
• writing .agents/AGENTS_TREE_REVIEW.md
• proposing cleanup, compaction, conflict resolution, and sharding plans
• auto-applying only trivial non-semantic hygiene fixes when they are clearly safe
• being the only non-distill skill allowed to touch tracked AGENTS.md, and only for those trivial non-semantic hygiene fixes

It does not own:

• writing AGENTS.override.md
• semantic doctrine changes without explicit human approval
• shard creation, shard moves, or meaning-changing conflict resolution without explicit human approval
• task-local packet work unless a current task explicitly asked for this audit as part of that packet

Audit workflow

1. Discover the tracked tree.
   • Enumerate all tracked AGENTS.md files.
   • Note any tracked AGENTS.override.md files as likely hygiene smells.
   • Build the effective hierarchy from root downward.
2. Audit file shape.
   • Confirm every tracked AGENTS.md has ## Scope.
   • Confirm section names stay canonical when present.
   • Flag missing, tautological, or low-value ## Scope sections.
   • Flag ## Entrypoints sections in deep leaf shards when they add no real wayfinding value.
   • Confirm other sections are present only when they contain real content.
   • Flag files that drift from canonical section names.
3. Audit lean-ness.
   • Treat broad overview prose, directory dumps, repeated boilerplate, and generic cookbook content as compaction smells.
   • Treat roughly 200+ lines as a review trigger for compaction or sharding, not an automatic failure.
4. Audit specificity.
   • Flag vague, non-verifiable instructions.
   • Prefer exact commands, stable owner/module names, hard constraints, and durable rationale.
   • Treat raw file-path links as a fragility smell unless they are unusually stable and clearly necessary.
5. Audit hierarchy quality.
   • Flag parent/child duplication when the child adds no meaningful specialization.
   • Flag local files that restate root doctrine instead of carrying only boundary-local guidance.
   • Flag guidance placed too high or too low relative to the stable owner boundary.
6. Audit conflicts and ambiguity.
   • Flag contradictory rules across parent/child tracked files.
   • Flag ambiguous wording that could lead different agents to make different choices.
   • Verify suspicious conflicts against code/tests before concluding.
7. Audit staleness.
   • Flag stale paths, commands, owner/module references, or other brittle anchors.
   • Flag entries that are now better encoded in code/tests and should be pruned.
8. Audit for task-state leakage.
   • Flag plan recaps, worklog residue, temporary migration notes, or current-task chatter that belongs in .plans/*, not tracked AGENTS.md.
9. Decide whether a trivial hygiene fix is safe.
   • Safe auto-fix classes:
     • section heading normalization to canonical names
     • whitespace / formatting cleanup
     • deduping exact duplicate bullets
     • removing obviously broken file references when the correct target is unambiguous
     • reordering within one section when meaning does not change
   • If any fix changes meaning, defers a judgment call, or changes topology, do not apply it automatically.
10. Write .agents/AGENTS_TREE_REVIEW.md.
    • Summarize current tree health.
    • Record any auto-applied hygiene fixes.
    • Emit concrete findings and approval-gated proposals.