document-pr

name	document-pr
description	Generate or update a per-branch Markdown record of the current PR/branch's work under docs/<branch-slug>.md, and upsert its entry in the docs/README.md index (newest first). Idempotent: re-running on the same branch updates the same file instead of creating a new one. Use after opening a PR, before merging, or when asked to 'document this PR/work'.

Purpose

Produce a durable, human-readable record of what a PR changed and why, stored in the repo so the team has a log of shipped work — one document per branch, newest first. Running the skill twice on the same branch must NOT create a second file; it refreshes the existing one.

When to run

• After creating a PR (gh pr create), or just before merging to capture the final state.
• When the user asks to "document this PR", "write a PR doc", or "record this work".

Inputs to gather (in this order)

1. Branch & PR metadata
   • git rev-parse --abbrev-ref HEAD — current branch (this keys the filename).
   • gh pr view --json number,title,body,url,headRefName,baseRefName,state,mergedAt — if a PR exists for the branch. If no PR yet, fall back to the branch name + the latest commit subjects and note "PR not yet opened" in the doc.
2. The diff being summarized
   • git log --oneline <base>..HEAD (base is the PR's baseRefName, else main).
   • git diff --stat <base>...HEAD for the file-level shape.
   • Read the actual diff for anything non-obvious; do NOT invent changes.

The per-branch doc (one file per branch)

Path: docs/<branch-slug>.md

• <branch-slug>: the current branch name, lowercased, with / and any non-alphanumeric run collapsed to a single -, trimmed of leading/trailing -. Examples: refactor/migrate-graphql-to-rest → refactor-migrate-graphql-to-rest; feat/BE-301_geo → feat-be-301-geo.
• Idempotency: before writing, check whether docs/<branch-slug>.md already exists.
  • If it does not exist: create it, set Created to today, and add a fresh index entry.
  • If it does exist: overwrite its body with the refreshed content, keep the original Created value, set Updated to today, and update (do not duplicate) the index entry.

Template:

# <PR title>

- **PR:** #<number> — <url>   (or "not yet opened")
- **Branch:** <headRef> → <baseRef>
- **Status:** <open | merged (<mergedAt date>) | draft | not yet opened>
- **Created:** <YYYY-MM-DD>
- **Updated:** <YYYY-MM-DD>   (omit if same as Created)
- **Author:** <git user.name>

## Summary
<2–4 sentences: what changed and why. Plain language.>

## Changes
<Bulleted list grouped by area/package. One line each, most significant first.>

## Verification
<How it was validated: analyze/tests/manual run. State outcomes plainly.>

## Notes / follow-ups
<Out-of-scope items, known gaps, linked issues. Omit if none.>

Keep it factual and concise. Report outcomes honestly (if tests failed or a step was skipped, say so).

The index (newest at top, one entry per branch)

Path: docs/README.md

• If it does not exist, create it:

  # PR / Work Log
  
  One entry per branch, newest first. Generated by the `document-pr` skill.
  
  <!-- entries below -->
  

• Each branch has exactly one index line, of the form:

  - **<YYYY-MM-DD>** · [<PR title>](<branch-slug>.md) — <one-line hook>
  

• Upsert rule:
  • If a line already links to <branch-slug>.md, replace that line in place (keep its current position; refresh the date/title/hook). Do NOT add a second line for the same branch.
  • Otherwise, insert a new line immediately under <!-- entries below --> so the newest branch is at the top.
• Never touch other branches' entries.

Steps

1. Gather the inputs above; compute <branch-slug>.
2. Create docs/ and docs/README.md if missing.
3. If docs/<branch-slug>.md exists, read it to preserve Created; then overwrite it. Otherwise create it fresh.
4. Upsert the branch's line in docs/README.md per the rule above.
5. Tell the user whether the doc was created or updated, its path, and the index line. Do not commit or push unless the user asks.