decision-doc-sync

# Documentation map

## ADRs

- Match the existing file naming, for example `docs/adr/0003-short-title.md`, using the next free number.
- If `docs/adr/` does not exist, create it only for a durable decision that has real alternatives.
- Minimum sections: Status, Context, Decision, Consequences.
- Never rewrite an accepted ADR; supersede it with a new one and update the old record's status.
- When an ADR skill is installed in `.agents/skills/`, load it for the format.

## Edge cases

- `CLAUDE.md` that only points to `AGENTS.md`: edit `AGENTS.md`, not the pointer.
- A decision that only affects one feature belongs next to that feature, not in top-level docs.
- Docs regenerated by a tool are edited at their source, not in the output.

---
name: decision-doc-sync
description: "Trigger: architecture change, new convention, UI/UX standard, quality gate change, ADR. Keep existing project docs in sync with structural decisions."
license: Apache-2.0
metadata:
  author: purrfold
  version: "1.0"
---

# Decision Documentation Sync

## Activation Contract

Load this skill when a change introduces or changes a structural decision: architecture, UI/UX standards, scripts or quality gates, or a cross-cutting convention.

## Hard Rules

1. Check which documents exist before editing; update only documents that exist, and create one only when a rule below requires it.
2. Keep each fact in one document and link to it from others instead of duplicating it.
3. Record the decision itself, not the change history.
4. Never leave a document contradicting the code after the change.

## Decision Gates

| Change type | Document |
| --- | --- |
| Architecture, folder structure, scripts | `README.md` |
| Visual or UX standard, tokens, component usage | `DESIGN.md` |
| Agent workflow, commands, operational guidance | `AGENTS.md` |
| Durable decision with alternatives and consequences | new record in `docs/adr/` |

## Execution Steps

1. Check which of `README.md`, `DESIGN.md`, `AGENTS.md`, and `docs/adr/` exist.
2. Classify the change with the table above; one change may hit several rows.
3. Update each affected document that exists.
4. For an ADR, follow the existing numbering and format in `docs/adr/`; see [references/doc-map.md](references/doc-map.md).
5. Reread the edited sections against the code.

## Output Contract

List every document updated, created, or deliberately skipped, with a one-line reason each.

## References

- [references/doc-map.md](references/doc-map.md) — ADR format and edge cases.