# Decision Map Maintenance

> Keep decision maps as concise routers from decisions to canonical documents and validation guardrails.

- Skill: `clawic/decision-map-maintenance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add clawic/decision-map-maintenance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/clawic/decision-map-maintenance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: clawic (https://skillmd.com/u/clawic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/clawic/decision-map-maintenance

---


# 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.