/write-docs

name: write-docs
description: >
  Create or update structured docs under docs/ with frontmatter, numbering,
  lifecycle status, and index regeneration — guides, references,
  troubleshooting, design docs and ADRs. Use for "write a doc", "document
  this", "create a guide", "write an ADR", "update the docs". For the
  system-design thinking itself (architecture, trade-offs, failure modes)
  use /ship:arch-design first — it hands back here to record the decision.

Documentation Standard

All structured docs live under `docs/`. Each subdirectory is a category (e.g., `docs/design/`, `docs/guides/`, `docs/troubleshooting/`). Follow this standard when creating new docs or modifying existing ones.

For design docs and ADRs, the thinking is a separate job: `/ship:arch-design` walks the design lenses (numbers, failure modes, trade-offs, red-team) and hands the decision back here. This skill governs how the result is recorded — design category conventions below, Boundaries required. If a design doc is requested and no analysis exists yet, run `/ship:arch-design` first.

Red Flag

**Never:**

• Lead with analysis instead of the decision
• Include implementation details that belong in code
• Mix languages within one document
• Silently delete history — mark superseded sections, don't erase them
• Create a doc without adding it to the docs index
• Mark a doc as `current` without verifying claims against code
• Skip the Boundaries section in design docs — it's the core anti-drift mechanism
• Ship a design doc with zero numbers and zero rejected alternatives —

that's a description, not a design

• Use a duplicate number within a category

Frontmatter (Required)

Every managed doc MUST start with YAML frontmatter:

---
title: "Human-readable title"
description: "One sentence, under 120 chars — enough for an AI to decide whether to read the doc."
category: "design"
number: "002"
status: current | partially-outdated | superseded | draft | not-implemented
services: [scripts, hooks]  # only when specific dirs/components are affected
superseded_by: "034"        # only when status is superseded
related: ["design/001", "guides/003"]  # category-qualified when cross-category
last_modified: "2026-04-13"
---

Required Fields

• **title**: Match the `# heading` below the frontmatter. Use quotes if it contains special chars.
• **description**: One concise sentence for the docs index — write it for an AI that needs to decide "should I read this doc?" without opening it. Max 120 chars.
• **category**: Matches the subdirectory name (e.g., `"design"`, `"guides"`, `"troubleshooting"`). Must be one of the subdirectories under `docs/`.
• **number**: Unique within its category. Zero-padded 3 digits (e.g., `"002"`, `"029"`). Used for file naming (`029-topic.md`) and cross-referencing.
• **status**: One of the 5 allowed values. See Status Lifecycle below.
• **last_modified**: ISO date (`YYYY-MM-DD`) when the doc was last updated. Must be updated on every edit.

Conditional Fields

• **services**: Array of affected directories or components.
• **superseded_by**: Required when status is `superseded`. Points to the replacement doc as `category/number`.
• **related**: Include when related docs exist. Array of `category/number` references for navigation.

Docs Index

After creating or updating a doc, regenerate the index:

# SKILL_DIR = this skill's base directory (announced as "Base directory
# for this skill" when the skill loaded) — your cwd is the user's repo,
# so a bare relative path will not find the plugin's scripts.
bash "$SKILL_DIR/../../scripts/generate-docs-index.sh"

This produces `docs/DOCS_INDEX.md` — a compact table (Category, #, Status, Name, Description, Last Modified, Path) that agents can read on demand to see what docs exist without opening each one. Superseded docs are excluded from the index.

Status Lifecycle

draft → current → partially-outdated → superseded
                ↘ not-implemented (if design was never built)

| Status | Meaning | |--------|---------| | `draft` | Proposed but not yet approved or implemented | | `current` | Content matches production code | | `partially-outdated` | Core content still applies but some details have drifted from code | | `superseded` | Replaced by another doc — must set `superseded_by` | | `not-implemented` | Approved but never built |

When changing status, also update `last_modified` to today's date.

Numbering & File Naming

• Next available number: check `ls docs/<category>/ | sort` and pick the next zero-padded 3-digit number (e.g., `003`, `010`).
• No duplicate numbers within a category. Each top-level doc or directory within a category gets a unique number.
• Sub-documents inside a directory (e.g., `design/014-credentials-vault/plan-1-vault-service.md`) share the parent number.

docs/<category>/{number}-{kebab-case-topic}.md

Example: `docs/design/029-prototype-v3-web-migration.md`

Document Structure

---
(frontmatter)
---

# {Number} — {Title}

## Status

{Status explanation with context — why it has this status, what changed}

## Summary

{2-3 sentences: what problem this solves and the key content}

## (Body sections — flexible per topic and category)

## References

- Related docs, external links, prior art

Writing Rules

• Lead with the decision or answer, not the analysis. Readers want to know "what" before "why."
• Use concrete file paths, struct names, and API endpoints — not abstractions.
• If the doc is in Chinese, keep it in Chinese. If in English, keep it in English. Don't mix.
• Mark superseded sections inline with strikethrough or a note, don't silently delete history.
• When content changes, update the existing doc rather than creating a new one — unless the change is a complete replacement (then supersede).

Category Conventions

design (architectural decisions)

• **Boundaries section required** — the core anti-drift mechanism
• **Recommen