doc-writer

name	doc-writer
description	Documentation skill for ADRs, READMEs, in-code docstrings, and reference material. Activate when the user asks for documentation, when a public contract changes without docs, or when an ADR is needed per the architect skill's output. Optimised for documents that age well.
type	skill
license	Apache-2.0
metadata	{"provenance":{"canonical":"${CANONICAL_REPO}","feedback":"${FEEDBACK_REPO}","version":"1.1.0"}}
claude	{"allowed-tools":["Read","Write","Edit","Grep","Glob"],"user-invocable":true}

Documentation Writer

A skill for writing documentation that survives the first refactor. Bias toward documents the next reader will actually read.

When to activate

• The user asks for a README, ADR, architecture doc, or in-code reference.
• A change shifts a public contract (CLI flags, API surface, config schema) and the existing docs no longer match.
• The architect skill produced a recommendation that warrants an ADR.
• A new module or component lacks a top-of-file docstring.

Do not activate for:

• Trailing summaries of "what I just did" — those belong in the PR body, not in standalone docs.
• Inline comments about what the code does — code already does that.
• Documentation that nobody asked for, just to look thorough.

Operating mode

1. Identify the reader

Documents written for an unspecified reader become unread. Before writing, name the reader concretely:

• Future maintainer — knows the codebase, needs the why and the invariants. Short, dense.
• Onboarding contributor — new to the codebase, needs the what and the how to run it. Longer, with examples.
• External integrator — does not have repo access, needs only the contract. API-doc style.
• Reviewer of an architecture decision — needs context, the decision, and the consequences. ADR style.

Match the doc's length and tone to the reader. A README for an external integrator and a README for a maintainer are not the same doc.

2. ADRs

Standard sections:

# ADR-NNNN: <decision>

## Status
<Proposed | Accepted | Deprecated | Superseded by ADR-MMMM>

## Context
<What forces this decision now? Constraint, deadline, incident, drift.
Three to five sentences. If you cannot fit the context in five
sentences, the decision is not crisp enough to record.>

## Decision
<One paragraph: what was decided, in declarative voice.>

## Consequences
- Positive: <what improves>
- Negative: <what worsens or constrains future moves>
- Neutral: <changes that are neither good nor bad but matter>

Number ADRs sequentially. Never edit an accepted ADR — supersede it with a new one and update the Status line of the old one.

3. READMEs

Section order, in priority:

1. One-sentence pitch — what the project does, for whom.
2. Quick start — three commands that produce a visible result.
3. Install / prerequisites — exact versions where it matters.
4. Usage — the two or three most common workflows.
5. Reference — links to deeper docs, not inline.
6. Contributing — link to AGENTS.md or CONTRIBUTING.md.
7. Licence — one line.

Skip sections that do not apply. A README that ends on section 3 because the project genuinely needs nothing more is correct.

4. In-code docstrings

Module / file top-of-file: one paragraph stating the module's role and the invariant it enforces, if any. Skip if obvious from the name.

Function / method docstrings: state the contract — pre-conditions, post-conditions, side effects, error modes. Do not restate the parameter types if the language already encodes them. Do not paraphrase the function name.

def transfer(amount, from_acct, to_acct):
    """Move `amount` from `from_acct` to `to_acct` atomically.

    Raises InsufficientFunds if `from_acct` balance < amount.
    Side effect: emits a `transfer.completed` event on success.
    """

5. Aging well

Before committing the doc, ask:

• What in this doc will be wrong in six months?
• Could that part live closer to the code (where it ages with the code) instead of in this doc?

If the answer is yes, prefer in-code docs over a standalone document. Standalone docs that drift silently are worse than no docs.

Output expectations

• Markdown, with proper heading hierarchy (no skipped levels).
• Line wrap to ~80 characters for prose; do not wrap code or tables.
• Internal links by relative path; external links with full URL.
• No emoji in body text unless the project's convention uses them.

Friction reporting

When a recognition signal fires (see config/TOOLS.md → Friction Reporting → Recognition signals), invoke the harness-report skill rather than reimplementing the protocol inline. The reporter walks you through identifying the offender, picking the room, and filling the payload.