finalize

# Finalize — distil a PR into its durable commit `/reflect` scatters provisional experience notes across a PR's WIP commits while the work happens. The PR then accumulates review feedback. **This skill compresses both into the one commit that survives the squash** — the durable, location-reachable record a future agent meets via `git log` / `git blame`. Vocabulary, subject convention, and format are defined once in [`../_shared/commit-trailers.md`](../_shared/commit-trailers.md) — **read it first**, then read this for *how to reconcile and where to put the output*. ## Where this sits ``` /reflect → WIP commit messages [episodic, provisional, disposable] PR review + bots → PR comments [external critique] ↓ THIS SKILL, just before squash /finalize → squash commit message [durable, location-reachable] ↓ fork promotion → learning skills / memory [cross-cutting, always-loaded] ``` ## The one principle: reconcile to the *end state*, not concatenate The easy version — collect every trailer and paste them in — is wrong, because **the PR's job is to change its own mind.** A WIP note the PR later contradicted must be **dropped**, not carried, or it lands frozen and wrong on `main`: > WIP commit 1: `Rejected: server-side sessions | too much infra`. Review pushes back; commit > 4 *adopts* server-side sessions. Concatenation carries `Rejected: server-side sessions` onto > `main` — now actively misleading. Reconciliation drops it (or flips it to a `Constraint`). So read the whole arc **in order** (commits + comments + check outcomes) and emit only what is still true at the end. This is judgment work — it's why this is a skill, and why it's a human-triggered pre-merge step, not an automated merge hook. ## Step 1 — Gather - **Author-side notes:** `git log --reverse main..HEAD --format='%(trailers:only,unfold)'` for the trailers, plus the commit bodies for the prose. **`--reverse` is required** — the arc walk in Step 2 is oldest-first, and the default `git log` order (newest-first) would invert the timeline and let stale, overturned notes win. (Drop the deliberate no-note commits.) Also fold in any PR comment carrying the `<!-- reflect-note -->` marker — those are author-side reflection routed to a comment because the commit was already pushed, **not** critique (see [`../_shared/commit-trailers.md`](../_shared/commit-trailers.md)). - **Reviewer/bot critique:** the PR comments **without** the `<!-- reflect-note -->` marker. Reuse `/docs:assess-comments` if available (it already collects, role-tags, and splits open/resolved across tools); otherwise read them directly (`gh api repos/<o>/<r>/pulls/<n>/comments`, `.../issues/<n>/comments`, `.../pulls/<n>/reviews`). Note which findings were *fixed* vs *dismissed* vs *still open*. - **Check outcomes:** whether CI / security / Bugbot ended clean. ## Step 2 — Reconcile Walk the arc in commit/comment order and produce the **end state**: - **Drop** any WIP note a later commit or review overturned. - **Merge** duplicates and near-duplicates into one line; prefer the latest, most specific. - **Resolve contradictions** in favour of what the final code actually does — verify against the diff, don't trust the note. - **Fold in review outcomes** as their *verdict*, not a transcript: a review thread that settled on a rule becomes one `Constraint:`; an approach the review killed becomes `Rejected:`. Copy what survived, not the conversation. - An *open* unresolved concern is **not** end-state knowledge — leave it on the PR, don't bury it in a trailer. ## Step 3 — Sort & propose promotion Same split `/reflect` Step 3 makes, now over the reconciled set: - **Location-bound** (a future agent editing this area needs it) → durable trailer on the squash commit. - **Cross-cutting** (must apply regardless of what's edited — a preference, a process rule, a standing gotcha, a project-wide constraint) → **propose** an edit to the relevant learning skill or a memory file. A commit can't guarantee it'll be seen. **Propose, don't apply silently** — show the user the exact addition and target file. ## Step 4 — Compose Write the distilled message per the shared shape: a `DOC-XXXX` subject, a tight body paragraph (the durable narrative for humans + the history bot), then the reconciled trailer block. Far fewer trailers than the inputs held — distillation is compression, not collection. Keep the **subject** and the **body-file** separate: the body-file holds the body paragraph and the trailer block **only — no subject line**. The subject is passed via `--subject` in Step 5, so repeating it in the file would duplicate the title into the commit body. ## Step 5 — Hand off (do **not** merge) This repo squashes with `squash_merge_commit_message = COMMIT_MESSAGES` (verified 2026-06-25), so the **default** squash body is every WIP commit message concatenated — exactly the raw dump we're avoiding. Override it explicitly; never rely on the default: ``` gh pr merge <n> --squash \ --subject "DOC-XXXX <summary>" \ --body-file <distilled-message-file> ``` Present three things and **stop**: 1. the distilled squash message (subject + body + trailers), 2. any promotion proposals (target file + exact addition), 3. the ready-to-run `gh pr merge … --body-file` command. The human triggers the merge. Reconciliation is judgment-heavy and a squash-merge is hard to reverse, so finalize *prepares*; it does not press the button. (An opt-in auto-merge could be added later, but it inherits all the risk below.) ## Limits (read honestly) - **Under-distilling is recoverable; a wrong frozen trailer on `main` is not.** When the arc is ambiguous, drop the trailer and leave the nuance in body prose. Bias to fewer, certain trailers. - It **reconciles text, it doesn't relive the work** — its only knowledge is what `/reflect` and the reviewers serialised. Garbage in stays garbage; verify contradictions against the actual diff. - A merge-time **automated backstop** (GitHub Action) is the weakest possible version of this — least context, no human, and under `COMMIT_MESSAGES` it must *also* override `--body-file` or it concatenates raw. Keep it phase 2, and conservative. - If Step 3 promotion is skipped, cross-cutting lessons die in a commit nobody re-reads and the always-loaded tier starves. It is not optional.