---

name: author description: 'Write a new doc in the right place with the right name. Use when asked to "write a doc", "where should this doc go", "add an ADR", "document this decision", "new spec", or "new feature plan".'

author

Author docs the docflow way: choose category → apply naming → fill template → cross-link. Companion of router (read side) and changelog (history). Templates live in the plugin's templates/ dir; /docflow:init drops them into a repo.

A doc's filename should tell a teammate what + when without opening it. If it can't, rename.

Writing style (enforce on every doc)

Direct, tech + business. No filler.

• Tables and bullets over paragraphs. One claim per line.
• Lead with the outcome/decision; cut "this document describes…", "in order to", "it is important to note".
• Concrete: names, paths, numbers, commit hashes. No adjectives that carry no info.
• Each section earns its place — if a placeholder stays empty, delete the section.
• Max one short intro line per doc; the structure does the rest.

---

1 — Pick the category (what is this doc?)

The doc answers…	Category	Folder
WHAT a feature does (user-facing)	product spec	product-spec/
HOW it's built (data flow, API contract, lifecycle)	technical spec	specs/
WHY we chose an approach	decision (ADR)	decisions/
HOW to do X / a convention / cheat sheet	reference	references/
WHAT's planned / status / roadmap	plan	plans/ (features/, hygiene/, upcoming/)
Current quality / known bugs / audit	review	reviews/ (active/, archive/, bugs/)
WHAT shipped, by month	changelog	changelog/ — see changelog

One doc, one category. If it spans two, it's two docs that cross-link.

---

2 — Apply the naming pattern

Folder	Pattern	Example
product-spec/	NN-topic.md (stable, reading order)	04-jobs.md
specs/	(mmm-yy)-topic.md (dated snapshot)	(apr-26)-tab-system-workflow.md
references/	topic.md (stable)	newtable-component.md
decisions/	NNNN-title.md (monotonic, never reused)	0001-url-as-state.md
plans/features/	(mmm-yy)-feature-name.md	(apr-26)-create-job-stepper.md
plans/hygiene/	(mmm-yy)-topic.md	(apr-26)-codebase-cleanup.md
plans/upcoming/	rolling roadmap, no dates	critical.md, now.md, next.md, later.md
reviews/active/,archive/	(mmm-yy)-topic.md	(may-26)-tab-system.md
changelog/	(mmm-yy).md	(may-26).md

Rules:

• kebab-case always — never camelCase or snake_case.
• (mmm-yy)- prefix on dated docs: lowercase 3-letter month + 2-digit year — jan feb mar apr may jun jul aug sep oct nov dec.
• Stable numbers (NN-, NNNN-) for ordered series that are not snapshots — product-spec reading order, ADRs.
• No redundant suffixes — never -feature.md, -spec.md, -doc.md. Add a qualifier only when a sibling would otherwise collide (tab-system-overview + tab-system-qa-guide).
• Topic prefix groups siblings so they sort together ((apr-26)-tab-system-*).

---

3 — Fill the template (or generate a draft from code)

Don't start specs/plans from blank — generate a draft from the real repo, then verify:

• Spec: bash scripts/docflow-spec.sh <code-path> → pre-fills files, exports (Architecture), types (Data), paths+verbs (API), hooks (Flow). You group + confirm + write Risks.
• Plan: bash scripts/docflow-plan.sh --days 30 → backlog candidates from TODO/FIXME + git churn. You triage into horizons.

Both write drafts marked <!-- auto -->; curate before shipping. Then fill manually where heuristics can't reach:

Each category has a skeleton in the plugin's templates/. Key shapes:

ADR (decisions/NNNN-title.md):

# NNNN — Title

> **Status:** proposed | accepted | superseded by [NNNN](...) | deprecated
> **Date:** YYYY-MM-DD
> **Deciders:** names/handles

## Context        — what forced the decision? constraints, prior pain
## Decision       — what we chose (one sentence, then detail)
## Consequences   — good / bad / what gets harder
## Alternatives considered  — each + why rejected

Write an ADR for: cross-cutting choices, non-obvious trade-offs, reversals (supersede the old one — never edit it). NOT for: version bumps, one-file refactors, taste.

Spec (specs/(mmm-yy)-topic.md): header block (Module: / Route: / Branch:), then numbered sections — architecture, data model, API surface, state, edge cases. Plus a Related: block linking plan + review + ADRs.

Feature plan (plans/features/(mmm-yy)-name.md): Status / Owner / Surface header, then ## What shipped (table w/ commit refs) · ## In flight · ## Queued.

Review (reviews/...): Last updated / Scope header, scorecard table, P0/P1/P2 findings.

---

4 — Cross-link (no orphan docs)

Bidirectional. The chain that ties a feature together:

product-spec/NN-feature.md   (WHAT)
   ↕
specs/(mmm-yy)-feature.md     (HOW)  ──► decisions/NNNN-*.md  (WHY)
   ↕
plans/features/(mmm-yy)-feature.md  (STATUS)
   ↕
reviews/active/(mmm-yy)-feature.md  (QUALITY)

• Every spec ends with a Related: list (plan, review, ADRs).
• Every ADR links the specs/product-specs it affects.
• The docs-root README.md indexes everything — add your new doc to it.
• Filenames with parentheses must be wrapped in angle brackets in links, or the renderer breaks: [text](<specs/(may-26)-file.md>) — not [text](specs/(may-26)-file.md).

---

5 — After writing

1. Regenerate the map: bash scripts/docflow-map.sh <DOCS_ROOT> → updates <DOCS_ROOT>/INDEX.md (the compact path — purpose tree every agent reads first). New doc needs a clear H1 — that becomes its one-liner.
2. Add the doc to the docs-root README.md index + the folder's own README if it has one.
3. Record the document change in ## Update Log or the feature/changelog table.
4. Run bash scripts/docflow-validate.sh --target <REPO ROOT> and fix validation errors before reporting completion.
5. If a decision shipped or a plan item completed, reflect it in changelog/ (see changelog).
6. On rename: update the file, grep -rn "old-name\.md" every cross-link, fix README entries, re-run the link check.

# link integrity — empty output = all local links resolve
bash scripts/check-links.sh <DOCS_ROOT>