# Pr Retrospective > 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. - Skill: `jposluns/pr-retrospective` (Agent Skill) - Install (CLI): `npx skillmds@latest add jposluns/pr-retrospective` - Raw SKILL.md: https://api.skillmd.com/api/skills/jposluns/pr-retrospective/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: jposluns (https://skillmd.com/u/jposluns) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jposluns/pr-retrospective --- # 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`](../../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 ` (the durable home shipped), `ROUTED to ` (a backlog bullet or bundle now carries it), `REJECTED ()`, `EXPIRED ()`, or `WATCH (fires on 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`](../validation-sweep-pr-scoped/SKILL.md) and [`validation-sweep`](../validation-sweep/SKILL.md)). 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`](../validation-sweep-pr-scoped/SKILL.md) (slash command `/validate-pr`): consumed-by `/retro` as input. - Sibling skill [`validation-sweep`](../validation-sweep/SKILL.md) (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`](../../governance/ai-assistant-workflow-disciplines.md): the five disciplines this skill operationalizes (specifically: the research-assistant discipline's hallucination-assessment update protocol).