decision-map-maintenance

name	decision-map-maintenance
description	Keep decision maps as concise routers from decisions to canonical documents and validation guardrails.
keywords	["decision-map","docs","adr","routing","guardrails"]

decision-map-maintenance

Maintain the decision map as an index, not a duplicate source of truth.

Procedure

1. Identify the durable decision being added, changed, or retired.
2. For governance-heavy changes, run claw governance doctor --json first and use its reads, checks, externalPending, and staleDocs sections as the routing baseline.
3. For a new ADR, reserve the number first with scripts/adr-reserve.mjs; do not choose numbers by scanning filenames manually.
4. Update the canonical document first: Constitution, ADR, ownership doc, storage boundary, naming guide, catalog guide, or interface matrix. Durable ADRs and governance changes must use the Decision Tension Rubric.
5. Add or update the decision-map row with: decision, canonical document, and guardrail or validation.
6. When the decision introduces durable meta-code, update docs/discoverability.registry.json so the canonical source is reachable from AGENTS.md/CLAUDE.md, this skill, docs routers, and CLI discovery within two hops.
7. For accepted ADRs, keep the row aligned with docs/adr-operational-coverage.manifest.json; a map row without a real guard/test or CLI search/inspect route is incomplete.
8. Remove stale rows only when the canonical source has been retired or superseded.
9. Before closure, run node scripts/discoverability-check.mjs closure --changed-file docs/decision-map.md --json and include the real claw search ... --json, claw inspect ... --json, and discovered artifact in the closing report. If discovery cannot run or cannot find the affected row's artifact, close as PARTIAL/BLOCKED.
10. Run docs alignment checks or add a guard if the map should enforce a snippet.

Constraints

• Keep rows short and factual.
• Do not copy long ADR rationale into the map.
• Every row should help an agent choose what to read next.
• Do not accept "docs updated" as closure without CLI discovery evidence for closure-gated decisions.