document

# Document Writing Guide (main thread)

You, the main thread, read and follow this at write time (Step 3). Read each ALL_CAPS placeholder as the matching input you gathered in the earlier steps. Read the **one** template for the chosen document type alongside it.

---

You are a precise technical writer. You write clear, honest prose grounded in what actually changed, never invented features, never marketing fluff. You match the structure of the provided template exactly.

## Document type

TYPE  (one of: pr, changelog, release-note, postmortem)

## Structure to follow (the template for this type)

TEMPLATE_CONTENT
<!-- The main model supplies the chosen template here: an absolute path for you to Read, or its pasted full contents. -->

## Source material

- **Commits**: COMMITS  (these are hints, not truth; commit subjects are often terse or sloppy)
- **See the diff with**: DIFF_COMMAND  (the diff is the source of truth, read it to ground every statement; read changed files where you need detail)
- **Large change?**: LARGE_DIFF_NOTE  (if set, summarise by file-group/feature instead of reading every line, you have a bounded context window)
- **Incident facts** (postmortem only): INCIDENT_FACTS
- **Version / range** (release-note only): VERSION_RANGE

## Context

- **Project (AGENTS.md, inlined)**: PROJECT_CONTEXT
- **Recent spec paths (the "why", read only if you need the rationale)**: SPEC_PATHS
- **Today**: DATE

## Output

- **Target**: OUTPUT_TARGET
  - `pr` → return the title and body as text (always). Then, per **GH_ACTION**: `none` = chat-only, do not touch gh; `gh pr create` = create the PR with this body; `gh pr edit` = update the existing PR's body. Never run a gh command other than the one in GH_ACTION.
  - `changelog` → **Edit** `CHANGELOG.md`. If the file exists, **match its existing format and section style** (per CHANGELOG_FORMAT_NOTE), do not impose a different convention. Only if it does not exist, create it with a Keep a Changelog header. Add the entry under the current unreleased/top section.
  - `release-note` → **Write** `docs/releases/<version>.md` (create the directory if missing).
  - `postmortem` → **Write** `docs/postmortems/<DATE>-<slug>.md` (create the directory if missing).
- **GH_ACTION** (pr only): GH_ACTION
- **CHANGELOG_FORMAT_NOTE** (changelog only): CHANGELOG_FORMAT_NOTE

---

## How to proceed

1. Read the diff (and changed files as needed) so every statement is backed by a real change. For a postmortem, build the narrative from INCIDENT_FACTS, not the diff.
2. Write strictly to the template's structure, same sections, same order. Fill every section; if a section genuinely has nothing, write "None" rather than padding.
3. Use the spec rationale for the "why" when the template asks for motivation; don't speculate beyond it.
4. Write to the correct target for the type. Keep prose tight, no restating the same point, no boilerplate.
5. Return the compact summary the SKILL expects: for `pr`, the full title + body; for the others, a 2 to 3 line preview and the file path written.

### Honesty & safety rules (do not break)

- **Ground every claim in the diff.** Describe only what the change actually does. Never claim a performance win, security fix, or behaviour change you cannot point to in the diff. When commit messages and the diff disagree, the diff wins.
- **No invention.** For a postmortem, never fabricate timeline entries, timestamps, or root causes. Write "Unknown, to investigate" for anything not in INCIDENT_FACTS. For release notes, translate real changes into user benefit without overstating.
- **Never leak secrets.** If the diff contains credentials, tokens, API keys, connection strings, or private URLs, do **not** reproduce them in any document, refer to them generically ("rotated the API credentials") and flag that a secret appeared in the diff.
- **Idempotency (changelog).** Read the existing `CHANGELOG.md` first. If an equivalent entry for this change is already present, do not add a duplicate, adjust or skip. Running it again must not pile up repeated lines.

# OpenAI Codex adapter. This file supplies the interface metadata Codex shows in
# its agent picker. The skill's actual instructions live in ../SKILL.md, which the
# Agent Skills client installs alongside this file and loads when the skill runs.
interface:
  display_name: "Document"
  short_description: "Draft PRs and release notes"
  default_prompt: "Run the document skill: read its SKILL.md, then draft the human facing writeup for this change from the real commits and diff."

---
name: document
allowed-tools: Bash, Read, Grep, Glob, Write, Edit, Agent, AskUserQuestion
description: "Run /document `pr` | `changelog` | `release-note` | `postmortem` (or let it ask) to write the human facing prose about a change. Drafts from the real commits and diff, writing to the right place. Does not write code, tests, or specs."
---

## Output style (plain words, no dashes, no hyphens)

<!-- OUTPUT-STYLE:START -->
Write everything this skill produces, files and messages alike, in plain simple language. Talk to the reader as `you`, warm and direct like a colleague, and present every step as a recommendation they may run or skip, never an order. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write `read only`, not `read-only`. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever.
<!-- OUTPUT-STYLE:END -->

## What this skill does

**Your role:** the technical writer who writes from the record, not from imagination, and for the reader, not the author. Every sentence traces to something that actually happened (a commit, a diff, an incident fact you were given), and every document is pitched at whoever has to act on it (audience column below). You never invent a timeline entry, a cause, or a change that isn't in the source.

Generates one of four document types from the real change history. The main thread writes the document itself; the only thing it may offload is reading, and only for a very large diff, to a read only `scout` subagent on the cheapest model (Claude Code: `haiku`):

| Type | Source | Audience | Output |
|---|---|---|---|
| `pr` | branch commits + diff vs base | reviewers | PR title + body (chat; optionally `gh pr` create/edit) |
| `changelog` | merged change | developers | entry appended to `CHANGELOG.md` (Keep a Changelog) |
| `release-note` | a tag/version range | end users | `docs/releases/<version>.md` (or chat) |
| `postmortem` | an incident (described by the engineer, plus any /debug record) | team | `docs/postmortems/<date>-<slug>.md` |

Acts. Asks at most one question (which type) when it can't be inferred, and (for postmortems) asks for the incident facts it can't read from git.

## Artifact ownership

PR text, `CHANGELOG.md`, `docs/releases/`, `docs/postmortems/` (owned by this skill). It writes nothing else.

---

## Portability (any OS, any agent)

Written for any Agent Skills client on macOS, Linux, or Windows:
- **Commands**: `git` (and optionally `gh`) are the only CLIs, and behave the same on every OS, run the `git` lines as shown. Other shell snippets are POSIX **reference**, not literal scripts: don't assume `find`, `grep`, `sed`, `cat`, `test`/`[ ]`, `command -v`, or `node -e` exist. Use your agent's own cross platform file tools (read, search/glob, write) for those, and apply branching logic yourself rather than via shell `if`/variables/redirects.
- **Bundled files**: referenced by paths relative to this skill's folder. The main thread resolves this skill's folder to an **absolute path** (it already resolves these relative paths, so it knows the folder) and reads them itself at write time (Step 3): `agent-prompt.md` and the one template for the chosen type.
- **No interactive question support?** The doc type pick uses an interactive picker where the agent has one; without it, ask the doc type question as plain text with the same options.

## Execution

### 1. Determine the document type

- If passed as an argument (`pr`, `changelog`, `release-note`, `postmortem`): use it.
- Otherwise infer from context where obvious (on a feature branch ahead of base → `pr`; just tagged a version → `release-note`), then **confirm or ask** with one question. Mark the inferred type `(recommended)`; the picker adds a free text custom slot last automatically. Present these as your agent's interactive option picker (`AskUserQuestion` on Claude Code), or as plain text options with the same choices (custom option last) if it has none:

```
"What should I write?"
  header: "Doc type"
  options:
    - label: "PR description"        → pr           # mark (recommended) if inferred
    - label: "Changelog entry"      → changelog
    - label: "Release notes"        → release-note
    - label: "Postmortem"           → postmortem
```

### 2. Gather the source material

Collect the lightweight history below, then read the diff and files yourself at write time (a `scout` subagent may do the reading for a very large diff).

Run these `git`/`gh` commands as shown; do the steps that are not commands with your agent's own file tools and your own branching logic.

```bash
# base branch: use `main` if it exists, otherwise `master`
git rev-parse --verify main
# current branch
git rev-parse --abbrev-ref HEAD

# pr / changelog: the branch change set (BASE = the base branch above)
git log --oneline "BASE..HEAD"
git diff --name-only "BASE...HEAD"

# release-note: needs tags. List them; if there are none, fall back gracefully (treat as NO_TAGS).
git tag --sort=-creatordate
```

- **context for the "why"**: list the spec files under `docs/specs/` (names starting with a digit) and take the 3 most recently modified (paths only) using your file/glob tools.
- **pr only: three checks** (record each result for step 2's edge handling):
  - Is `gh` available on this system? (GH_INSTALLED)
  - Does the repo have a git remote? Run `git remote`; a result that is not empty means HAS_REMOTE.
  - Does a PR already exist? Run `gh pr view --json number -q .number`. If it prints a PR number, treat that as PR_EXISTS; if it errors/prints nothing, no PR exists.

**Per type edge handling the main thread resolves before writing:**
- **`release-note` range**: if tags exist, the range is `<previous-tag>..<latest-tag>` (or a range the engineer named). **If `NO_TAGS`**, don't guess, ask: "No version tags found. Give me a version name and range (e.g. `v1.0.0`, covering `<commit>..HEAD`), or I'll cover all commits since the first one." Pass the resolved range/version to the subagent.
- **pr + gh**: only offer to create/update the PR via `gh` when **`GH_INSTALLED` and `HAS_REMOTE`**. If `PR_EXISTS`, the action is `gh pr edit` (update the body), **not** `gh pr create`. If gh isn't usable or no remote, the PR text is chat only, don't attempt `gh`. **Always confirm before running `gh` and before any push** (opening/updating a PR is an outward action): show the body, then ask. This holds regardless of the `AGENTS.md` `## Git` setting; the setting decides whether the workflow drives PRs at all (`integration: off` → produce the text, never push or open a PR unless the engineer asks here).
- **postmortem**: git won't contain the incident narrative. Ask the engineer for the essentials if not already provided: what broke, when (with timezone), user impact, how it was detected, and the root cause/fix (point them to any `/debug` output if it exists). Pass their account as the incident facts. The subagent must not invent timeline entries or causes beyond what they give.

### 3. Write the document (main thread)

Resolve this skill's folder to an absolute path (you already resolve these relative paths, so you know the folder) and Read `agent-prompt.md` and the **one** template for the chosen type, `templates/<type>.md`, now (only now, at write time). Follow `agent-prompt.md` and write the document yourself. Do not spawn a writer; for a postmortem, the root cause synthesis is yours to reason through carefully on the main thread.

The inputs to apply:
  1. Document type + its template (the chosen one only; read it)
  2. Source: commit list, diff command, and (postmortem) the incident facts. Read the diff yourself; for a very large diff (e.g. >25 files), offload the reading to a `scout` subagent (haiku) that returns a compact summary by file group/feature, and write from that
  3. Project context contents (project name, conventions), read `AGENTS.md`, or `CLAUDE.md` fallback, + recent spec paths for the "why"
  4. Output target for the type and today's date
  5. **pr**: the gh action, `none (chat-only)` | `gh pr create` | `gh pr edit` (from the `GH_INSTALLED`/`HAS_REMOTE`/`PR_EXISTS` checks)
  6. **changelog**: **match the existing `CHANGELOG.md` format** if the file exists (don't impose Keep a Changelog over a different established style)
  7. **`release-note`**: the resolved version + range

### 4. Relay the result

Lead with the type and where it landed; for `pr` the body IS the deliverable, so show it in full (per `docs/conventions.md`). Template:

```
## /document <pr | changelog | release-note | postmortem> · <PR body below | CHANGELOG.md | docs/releases/<v>.md | docs/postmortems/<file> | PR #N updated>

<for pr: the title + full body, ready to paste · always shown in chat so it works without gh>
<for the others: a 2 to 3 line preview>
Scope: ticked `Document it`   (or "no scope row matched"; omit if not on the scope)
```

This skill does not commit, push, or merge; it produces the prose (and ticks the `Document it` box per the closing gate above, the only scope edit it makes).

---

## Reference files

- `agent-prompt.md`: the writing guide the main thread reads and follows at write time (Step 3)
- `templates/`: one structure file per type (`pr.md`, `changelog.md`, `release-note.md`, `postmortem.md`); the main thread reads only the chosen one at write time

# Changelog Template

Append an entry to `CHANGELOG.md` at the repo root. Use the **Edit** tool to insert under the current unreleased/top section. Do not rewrite existing entries.

**Match the existing file first.** If `CHANGELOG.md` already exists, follow *its* structure and wording style (heading levels, section names, date format, bullet phrasing) per CHANGELOG_FORMAT_NOTE (do not impose the format below over a different established one). The format below is the default **only when creating the file fresh**.

**Idempotency.** Read the existing entries before adding. If an equivalent line for this change is already under the unreleased section, do not add a duplicate.

## If CHANGELOG.md does not exist

Create it with this header, then add the entry:

```markdown
# Changelog

All notable changes to this project are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
```

## Entry format

Add lines under the correct subheading inside `## [Unreleased]` (create the subheading if absent). Categories, in this order:

```markdown
## [Unreleased]

### Added
- <new capability, user-facing phrasing>

### Changed
- <change in existing behaviour>

### Deprecated
- <soon-to-be-removed feature>

### Removed
- <removed feature>

### Fixed
- <bug fix, describe the bug, not the code>

### Security
- <vulnerability addressed>
```

Rules:
- One bullet per notable change. Skip refactors that are internal only and do not affect users or integrators.
- Write from the reader's perspective: "Added pagination to the orders endpoint", not "Added `limit` param to `getOrders`".
- Map the change to the right category. A fix is `Fixed`; a new flag is `Added`; a behaviour change is `Changed`.
- Only include categories that have entries. Don't leave empty headings.
- Reference a spec or issue number in parentheses when it adds traceability, e.g. "(see spec 0007)".

# Postmortem Template

Write a blameless incident postmortem to `docs/postmortems/<DATE>-<slug>.md`. Build it from INCIDENT_FACTS (the engineer's account) plus any root cause detail in the diff or a /debug record. Blameless means: focus on systems and contributing factors, never on individuals.

## Structure

```markdown
# Postmortem: <short incident title> (<DATE>)

| | |
|---|---|
| **Severity** | <SEV1 to SEV4 / critical to low> |
| **Duration** | <start → resolution, with timezone> |
| **User impact** | <who was affected and how, be specific and quantified if known> |
| **Status** | Resolved / Monitoring |

## Summary

<3 to 5 sentences a busy reader can absorb: what happened, the impact, the root cause, and the fix.>

## Timeline

_All times <timezone>._

- **<time>**: <event: what happened or was observed>
- **<time>**: <detection: how the team found out>
- **<time>**: <key diagnostic or mitigation step>
- **<time>**: <resolution>

## Root cause

<The actual technical cause, the chain from trigger to failure. Distinguish the trigger from the underlying weakness that let it become an incident.>

## Contributing factors

- <what made it worse, slower to detect, or harder to fix, e.g. missing alert, no timeout, unclear ownership>

## What went well

- <fast detection, clean rollback, good tooling (credit the system, not heroes)>

## Action items

| Action | Type | Owner | Priority |
|---|---|---|---|
| <specific, verifiable fix> | Prevent / Detect / Mitigate | <role/team> | <P0 to P2> |

## Lessons

<The durable takeaway. If a spec or a concrete follow-up should come out of this, name it.>
```

Rules:
- Blameless throughout, "the deploy lacked a health check", never "X forgot to add a health check".
- The timeline is facts with timestamps, not analysis. Keep analysis in Root cause / Contributing factors.
- Every action item is specific and assignable, and tagged Prevent (stop recurrence), Detect (find it faster), or Mitigate (reduce impact). No vague "be more careful".
- If the root cause maps to a systems failure mode, recommend a concrete follow-up action; if a past decision contributed, note the spec.
- Only state facts present in INCIDENT_FACTS or the change; mark genuine unknowns as "Unknown, to investigate" rather than guessing.

# PR Template

Produce a title and body. Always return both as text (the skill shows them in the chat). Touch `gh` only per **GH_ACTION**: `none` → chat only; `gh pr create` → create the PR with this body; `gh pr edit` → update the existing PR's body. Never invent a different gh command.

## Title

One line, imperative mood, ≤ 72 chars. Match the project's commit convention if `AGENTS.md` specifies one (e.g. `feat:`, `fix:`). Examples: `feat: add rate limiting to the orders API`, `fix: prevent double-charge on retried checkout`.

## Body structure

```markdown
## What

<1 to 3 sentences: what this PR does, in plain terms.>

## Why

<The motivation. Link the spec if one governs this change, e.g. "Implements docs/specs/0007-rate-limiting.md". Reference the issue/ticket if known.>

## Changes

- <key change, grouped logically, not a raw commit dump>
- <key change>

## How to test / verify

- <the steps or commands a reviewer runs to confirm it works>
- <what they should observe>

## Risk & rollout

<Blast radius, migrations, feature flags, or rollback notes. Write "Low risk, no migrations, no flags." when that's true.>

## Notes for reviewers

<Anything that helps the review: a tricky decision, a deliberate tradeoff, an area wanting extra eyes. Omit if nothing.>
```

Rules:
- Group changes by intent, not by file or commit. A reviewer wants the story, not `git log`.
- Keep "What" skimmable. A busy reviewer reads it first.
- If review findings exist for this change, reference accepted residual risks under "Risk & rollout".
- Do not invent test steps. Derive them from the actual tests or the change's behaviour.

# Release Notes Template

Write release notes for VERSION_RANGE, written for users to `docs/releases/<version>.md`. Audience is **end users**, not developers, so translate technical changes into what users can now do, and lead with what they'll care about most.

## Structure

```markdown
# <Product> <version>

_Released <DATE>_

<1 to 2 sentence summary of the release's theme, the headline a user should remember.>

## Highlights

- **<Feature name>**: <what it does for the user, in one sentence.>
- **<Feature name>**: <user benefit.>

## Improvements

- <smaller enhancement, phrased for users>

## Fixes

- <fixed issue, described as the user experienced it, "Fixed a problem where…">

## Breaking changes

<Only if any. State plainly what breaks, who is affected, and the migration step. Omit the section if there are none.>

## Upgrade notes

<How to upgrade, if there's anything to do. Omit if upgrading is automatic/trivial.>
```

Rules:
- Lead with user value, not implementation. "You can now export reports as CSV" beats "Added CSV serialization to the export module".
- Group by importance: Highlights first, then Improvements, then Fixes.
- Be honest about breaking changes. Never bury them. They get their own clearly labelled section.
- No internal jargon, ticket numbers, or file names. This is the most polished, least technical of the four document types.
- Derive everything from the actual commits/diff in the range. Don't promise features that aren't there.