Change Documentation Writer

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.

# 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