author

author

Author docs the docflow way: choose category → apply naming → fill template → cross-link. Companion of [router](../router/SKILL.md) (read side) and [changelog](../changelog/SKILL.md) (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](../changelog/SKILL.md) |

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](../changelog/SKILL.md)).
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>