pr-retrospective

name	pr-retrospective
description	Per-PR process retrospective, run as a PR's finalizing step before merge. Surfaces what went well, what caused friction, recurring patterns, and proposed improvements. Output is one entry per PR in the improvement-log register; recurring patterns become candidates for pack-rule updates, worker-brief template additions, or new audit gates. Invoke after the PR-scoped validation sweep (`validation-sweep-pr-scoped`; the parent library's `/validate-pr`) returns and before the next-PR planning step.
derives_from	../../governance/ai-assistant-workflow-disciplines.md

PR Retrospective

Project wiring (the parent library's instantiation; adopters substitute their own)

Portable procedure, concrete names. In the parent GRC library this skill runs with:

• Improvement-log register: the improvement-log register in the consuming project's working state (the append-only per-PR retrospective register this skill writes; one row per merged PR).

• Worker-hallucination metrics register: the worker-hallucination-metrics ledger in the consuming project's working state (the apply-time worker-correction log consumed as retrospective input).

• Worker-brief template: the worker-brief template in the consuming project's working state (the worker-side guard-rail carrier that pattern findings may extend).

• Sibling per-PR validation-sweep history register: the register in the consuming project's working state (whose reverse-chronological row convention the improvement-log register mirrors).

• The parent register's concrete table header keeps its original columns (Date | PR | FR closed | ...); the generic output format below names that column Backlog item closed, and the parent's paired slash-command stub carries the concrete form.

An adopting project maps each bullet to its own records; the procedure below refers to them generically.

Overview

After the PR-scoped validation sweep and before merge, conduct a brief retrospective on the PR's process. (Command names /retro, /validate-pr, and /validate are the parent library's paired commands, used in this document as shorthand; an adopting project reads them as its own equivalents.) The retrospective is light-touch (one entry per PR, 3-5 sentences) rather than a deep analysis; the value emerges over time as patterns surface across many entries.

The output is the improvement-log register (the project wiring above names the parent library's location; adopters relocate to a project-appropriate location). The register is append-only at the row level, ordered by PR number; the step-6 disposition scan appends tokens to earlier rows' Proposed-improvement cells without rewriting their original text. Each row carries the date, PR number, backlog item closed (if any), what-went-well note, friction note, pattern-surfaced note (if any), and proposed improvement (if any).

The skill is the orchestrator-side process-improvement loop. It pairs with the worker-side worker-brief template (per governance/ai-assistant-workflow-disciplines.md §1 hallucination-assessment update protocol) and the apply-time-catch tracking in the worker-hallucination metrics register (both named in the project wiring above). Together the three close the per-PR learning loop:

• Worker-brief template catches recurring worker-side failure modes before they reach the orchestrator.
• Apply-time catches log orchestrator-side verifications of worker output.
• PR retrospective surfaces process-level patterns that warrant pack-rule updates, new gates, or worker-brief additions.

When to Use

• Mandatory as a PR's finalizing step, before merge, immediately after the PR-scoped validation sweep returns. It runs paired with that sweep, with both record rows committed in-PR before the merge. (The parent library's concrete sequence: /validate-pr -> /retro -> write rows in-PR -> commit -> CI -> merge -> sync main -> delete branch -> next-PR planning.)
• The retrospective is one entry per PR. If a PR cycle produced findings, the entry carries them as observed friction. If a PR cycle was clean, the entry carries the clean-result observation.

No orchestrator-side skip discretion. Same discipline as the PR-scoped validation sweep: every PR gets its retrospective entry before merge (the one documented exception is a session-closing handoff PR that took the QA-fallback skip), even when the conclusion is "nothing new to learn." Zero-content entries (clean PR, no friction, no pattern surfaced) record that fact and serve as the proof-of-discipline (a uniformly-clean register-entry sequence is itself a signal that the workflow is calibrated). Skipping is a policy deviation requiring maintainer authorization.

Process

The retrospective runs in six short steps.

1. Identify the PR and its inputs

Capture:

• PR number, the PR's head SHA (the merge SHA is reconciled post-merge if it is needed), backlog item(s) closed (if any).
• The /validate-pr findings just returned (0 findings, N findings with categories, or out-of-window observations).
• Any apply-time worker corrections logged in the worker-hallucination metrics register during the PR.
• Recently-shipped PRs in the same cluster (for pattern surfacing).

2. Identify what went well

One short observation. Examples:

• "Mechanical alignment to canonical source; no decision needed."
• "Subagent's deep-read caught the multi-surface inconsistency before the maintainer had to."
• "Row recorded in-PR before merge; no next-PR batching needed."
• "Pass-1 verification surfaced two real defects the original drafting missed."

If there is genuinely nothing notable, record "Routine; no notable highlight." That's a fine entry.

3. Identify friction

One short observation. Examples:

• "Standards-currency gate flagged the template's illustrative Rev. 4 → Rev. 5 example as superseded; reworded to generic framing."
• "In-flight self-correction prose escaped into the CHANGELOG entry; caught by /validate-pr."
• "A backlog finding double-counted across two triage buckets."
• "Linter gap: Python ipaddress.is_private doesn't include CGNAT on Python < 3.13; PR required explicit allowlist update."

If there was genuinely no friction, record "No friction observed." That's also a fine entry.

4. Surface patterns (if any)

If the friction in this PR matches a friction seen in a recent PR (≤ 5 PRs prior), record the pattern. Examples:

• "Third consecutive findings-producing /validate-pr (#N → 2; #N+1 → 2; #N+2 → 2). Pattern: meta-PRs that touch fitness-review and validation artefacts introduce subtle multi-surface drift."
• "Recurring acronym-expansion gap in adopter-facing surfaces (PR #N README; PR #M README; PR #P README). Pattern: each new README polish needs first-occurrence expansion checked against the existing convention."

Patterns drive proposed improvements (step 5). A single occurrence is observation; a second occurrence is signal; a third is pattern. When a pattern's recurrence count (across the improvement-log Pattern column) reaches three or more distinct PRs, it AUTO-GRADUATES to a gate-or-convention proposal in step 5: name the mechanical check that would extinguish it (a false-positive-free gate where one exists, else a convention line), because checklist prose demonstrably reduces but does not stop a thrice-recurring class.

5. Propose improvement (if any)

If a pattern surfaced, name a concrete improvement. Examples:

• "Add a regression-test fixture exercising CGNAT detection to the PII-in-content linter."
• "Add an acronym-expansion-discipline note to the worker-brief template's DO list."
• "Codify the no-skip-discretion discipline in the validation-sweep-pr-scoped SKILL." (an actual early retrospective outcome in the parent library, recorded retroactively.)
• "Promote the 'genericize counts in prose where the directory is the canonical authority' principle into a pack-rule."

The improvement is a candidate for a future PR, not work shipped in this entry. The register tracks the candidate; the next planning cycle picks it up if priority warrants.

If no pattern surfaced, leave the proposed-improvement cell empty.

6. Disposition scan (closure discipline)

Proposed improvements accumulate un-codified and their classes recur unless each candidate is eventually closed. After appending the row, run the closure scan:

• Disposition what this PR landed. If this PR codified or routed any earlier row's candidate, append the disposition token to that row's Proposed-improvement cell per the register's disposition convention: CODIFIED in <carrier> (the durable home shipped), ROUTED to <destination> (a backlog bullet or bundle now carries it), REJECTED (<reason>), EXPIRED (<date>), or WATCH (fires on <n>th occurrence) (the sanctioned holding state for conditional candidates). A non-empty cell with no token is pending by definition.
• Carried-candidates check. When this PR performed an authorized protected-file touch, grep the register's pending cells for carrier phrases ("next authorized touch", "row is the carrier", "next CLAUDE.md-touching") and confirm the touch carried them, or record why it did not (the dropped-candidate shape: a carried clause silently missing from the touch it waited for).
• Rejection and expiry are maintainer calls. The scan proposes a REJECTED or EXPIRED disposition for an aged candidate; the maintainer dispositions it. The assistant never silently drops a pending candidate (the same no-drop discipline the sweep skills carry).

Output format

Append a row to the improvement-log register (named in the project wiring above):

| Date | PR | Backlog item closed | What went well | Friction | Pattern (if any) | Proposed improvement |
|---|---|---|---|---|---|---|
| YYYY-MM-DD | #N | item id (if any) | [1-2 sentences] | [1-2 sentences] | [1 sentence, blank if none] | [1 sentence, blank if none] |

New rows on top (reverse-chronological, matching the per-PR validation-sweep history register's convention).

The register's preamble describes the column semantics and links to this SKILL.

Termination

Single-iteration cycle: identify → analyze → record → disposition-scan. One entry per PR.

There is no looping. The slash command /retro is fire-and-forget retrospective. The register accumulates entries; pattern recognition emerges from the accumulation, not from any single entry.

Surfacing entries in chat

When the retrospective surfaces a Pattern or Proposed-improvement entry, surface it in the chat reply (per the chat-surfacing discipline shared with /validate and /validate-pr). The maintainer should see proposed improvements at the moment they're identified, not on their next deep-dive into the working-state archive.

For clean-PR retrospectives (no friction, no pattern, no proposed improvement), one-sentence chat acknowledgement suffices.

Same-PR recording (recursion-avoidance retired)

The improvement-log entry for a PR appends to the register and is committed into the SAME PR, recording that PR's own number: the retrospective is conducted immediately after /validate-pr and before merge, and its register row rides in-PR rather than batching into a next PR (per the synchronous model in validation-sweep-pr-scoped and validation-sweep).

A retrospective that surfaces a candidate improvement deserving its own PR (e.g., a new audit gate, a new pack-rule, a worker-brief template addition) DOES trigger that PR; but the substance of that PR is the improvement itself, not the register row. The register row still rides in the PR being finalized (recording its own number); the improvement PR carries only the improvement, plus its own /validate-pr + /retro rows.

Red Flags

• Skipping /retro because "this PR was routine; nothing to learn." No-skip discretion applies; record "Routine; no notable highlight" and move on.
• Treating /retro as deep analysis. The design is light-touch. Single-paragraph entries are correct.
• Treating the register as an action queue. The register tracks candidates; the next planning cycle picks them up.
• Failing to surface pattern-and-proposed-improvement entries in chat. The chat surface is for maintainer awareness; the register is for archive.
• Conducting /retro before /validate-pr completes. The retrospective consumes /validate-pr findings as input; running it first misses that input.

Verification

The retrospective is complete when:

• One entry appended to the improvement-log register for the PR being finalized.
• Pattern and Proposed-improvement entries (if any) surfaced in chat.
• Register entry includes the date, PR number, backlog item closed (if any), and the short observation cells; any disposition tokens from the step-6 scan are appended to the originating rows.

Common Rationalizations

Rationalization	Reality
"This PR was routine; nothing to retro"	The discipline of writing the entry is itself the value. A uniformly-clean register-entry sequence is a calibration signal.
"I'll bundle retros for several PRs together"	The retrospective consumes /validate-pr's findings as input; bundling loses the input freshness. One entry per merge.
"The pattern is obvious; no need to record it"	Patterns visible in the moment fade as the session progresses. Recording locks them in for cross-session learning.
"I'll surface the pattern when I'm sure it's a pattern"	First occurrence is observation. Second is signal. Third is pattern. Record at each stage; the register's accumulated view shows when the pattern crystallized.

See Also

• Sibling skill validation-sweep-pr-scoped (slash command /validate-pr): consumed-by /retro as input.
• Sibling skill validation-sweep (slash command /validate): the broader project-wide validation cycle.
• Worker-brief template (project-local; named in the project wiring above): codifies worker-side guard rails that /retro patterns may surface as additions.
• Worker-hallucination metrics register (project-local; named in the project wiring above): tracks apply-time worker corrections that /retro may surface as pattern candidates.
• Canonical rule ai-assistant-workflow-disciplines: the five disciplines this skill operationalizes (specifically: the research-assistant discipline's hallucination-assessment update protocol).