goberomsu/craft-skills/document

document

Author and file project documentation so every artifact lands at exactly one canonical location with the right template. Success: a reader or agent can always answer "where does this go?" without guessing. Run unslop as the final pass over the prose this skill writes; code and fixed machine formats are excluded.

Requirements

• POSIX find, sed, grep (BSD or GNU) — the root-doc-sprawl check below.

Artifact types (MECE)

Every documentation artifact answers exactly one question; never let one artifact try to answer two.

Routing

Pick the primary question a task answers and route by that row — the ontology table above for the six ontology artifacts, or the table below for repo-level artifacts and standing conventions. Create a decision artifact only when the user explicitly asks to record a decision or write an ADR; otherwise keep research, specs, plans, and rules in their own lanes and note decision candidates inside that artifact.

No documentation task should dead-end here — every repo-level artifact and every ontology artifact has an exit row.

Nearest-neighbor boundary

design owns DESIGN.md, visual direction, UX audits, and design-system work; route those requests there. readme owns the repository README.md; route README authoring there.

References vs research: a references file is a verbatim static copy of an external document; a research file is your own synthesis. Never merge them.

Rule vs ADR: the what to do goes in a rule. Load references/adr.md only when the user explicitly asks for an ADR or decision record.

Root-doc-sprawl check

Loose .md files accumulate at the repo root instead of filing into the ontology above. Count them, excluding the conventional set:

find . -maxdepth 1 -name '*.md' | sed 's|^\./||' | grep -viE '^(readme|agents|claude|changelog|contributing|license|code_of_conduct)\.md$' | wc -l

More than 3 is a signal to investigate the loose documents and propose their canonical docs/ paths before adding more. Do not move existing documents without an explicit request.

Decision boundaries

research (facts found)  |  decision/ADR (explicit record request)  |  plan (implementation built)

Research collects evidence and presents options; it does not decide. A plan sequences implementation; it may mention trade-offs without spawning a decision record. An ADR is an explicit destination, not an automatic distillation step. When routing is unclear, ask which artifact the user wants: evidence, a recorded decision, or implementation sequencing.

docs/ layout

Scaffold only the canonical directories and repository documentation artifacts requested; do not create empty placeholder files or move existing documents without an explicit request.

docs/
├── research/                     # Fact collection — sources, comparisons (pre-decision)
│   ├── {slug}.md
│   └── references/               #   verbatim static archives of external documents
│       └── {slug}.md
├── exec-plan/
│   ├── active/{slug}/             #   spec.md + plan.md while work is in progress
│   └── archive/{slug}/            #   same folder, moved here when done/discarded/superseded
├── decisions/                     # Cross-cutting ADRs — permanent, never deleted
│   ├── README.md                  #   ADR index + lifecycle reference
│   └── ADR-NNN-{topic}.md
├── rules/
│   └── {topic}.md
└── architecture.md                # Living system map — see architecture.md section below

Scratch drafts live outside docs/ and are not git-canonical. Finalizing a draft means moving it into docs/ at the correct path, then deleting the scratch source.

Lifecycle — spec and plan

spec drafted (scratch) → MOVE → docs/exec-plan/active/{slug}/spec.md
plan drafted (scratch) → MOVE → docs/exec-plan/active/{slug}/plan.md
                                  FINALIZE only when the user explicitly adopts the immutable-plan contract
work done / discarded / superseded → add status: done|discarded|superseded (+ superseded-by: {slug} when applicable) → MOVE active/{slug}/ → archive/{slug}/
user explicitly requested a decision record → create/update docs/decisions/ADR-NNN-{topic}.md (references/adr.md)

Lifecycle = folder position. A plan is active or archived by where its folder lives, never by a status field alone; move the whole {slug}/ folder, never split spec and plan.

Supersede timing: when creating a superseding plan-B, archive plan-A in the same action, before beginning plan-B's execution.

Finalized-plan contract: a working plan remains editable after commits. Set finalized: true only when the user explicitly adopts its body as immutable; from then, a scope change gets a new slug and the old plan's frontmatter is updated to status: superseded + superseded-by: {new-slug}. Only the finalization and lifecycle frontmatter changes after finalization.

Slug naming

Format: {kebab-description} — lowercase, hyphens only, no date prefix, no issue number. The folder (or filename) is the authoritative slug; a frontmatter slug that disagrees with it is an error.

architecture.md

Answers "how is this system put together?" for someone who just opened the repo: an annotated directory tree, component boundaries, a cross-cutting-decisions index (links to ADRs, not restatements), and the one or two data/control flows that matter most.

Update it whenever a change moves a component boundary or a new cross-cutting decision lands — not on every commit. Staleness signal: its directory tree or ADR index no longer matches reality. Keep it a map: if a section starts duplicating an ADR body, replace the duplication with a link.

Trivial exemptions — no spec/plan required

• Typo, comment, or wording fixes
• Lint- or format-only changes
• Dependency patch-version bumps (x.y.Z)
• Behavior-preserving renames

Anti-patterns

• Implicitly creating or scheduling an ADR because research, a plan, or a durable choice mentions a decision → keep the original artifact in its lane and create an ADR only when the user explicitly asks to record one.

Verification

• [ ] Each artifact answers exactly one question (an ontology row or a routing-table row) — none dead-ended
• [ ] Any ADR was created only from an explicit ADR / decision-record request
• [ ] Completed/discarded work moved active/ → archive/ with a status line
• [ ] architecture.md reflects the latest component boundaries and decisions, or was flagged stale
• [ ] References files hold verbatim source content, not synthesis
• [ ] Slug matches its folder/filename exactly
• [ ] Root-doc-sprawl check run when loose root docs are suspected; any relocation was proposed and explicitly requested before moving files