/release-retrospective

name: release-retrospective
description: "Produce a structured look-back after a major release or deprecation — capturing what the plan got right, what it missed, and what to do differently. Trigger when someone says: release retrospective, post-release review, what went wrong with the release, how did the deprecation go, release post-mortem, retro on the migration, or anything about reviewing how a release or deprecation actually went compared to the plan."
references:
  - ../../knowledge-notes/component-governance.md

Context

Governance currently looks forward: plan the deprecation, estimate the blast radius, write the migration guide. There's no structured skill for reviewing how it actually went. Did the blast radius estimate hold? What did the communication miss? Where did teams get stuck despite the migration guide? A release retrospective completes the governance loop and builds institutional knowledge that keeps a system from repeating the same mistakes across team transitions.

The retrospective is not a blame exercise. It's a learning artifact. The goal is: what changes to our governance process will prevent this specific gap next time? Foreseeable gaps reveal process failures. Unforeseeable gaps become new guardrails.

Key principles

**From component-governance:** Governance owns the release plan: who's affected, when they're affected, what they need to succeed. The plan is a hypothesis. The retrospective tests it. Blast radius, communication, migration path quality, timeline, and support burden are the five surfaces where plans often break. Each surface has a classification: was this predictable with better analysis, or genuinely novel?

**Key principle for retrospectives:** The plan was made with incomplete information. The retrospective reveals what information was missing. That gap is the insight — not a failure, a discovery.

Configuration

Before writing the retrospective, gather these inputs:

1. **Release or deprecation:** Component name, token set change, system-level refactor, or major version bump. What changed? 2. **Original plan:** Link to the deprecation plan, migration guide, communication package, or governance decision record. Paste key dates, blast radius estimate, phased rollout plan if one existed. 3. **Actual execution:** When did it ship? What was the actual timeline? Which teams/codebases were affected (names or counts)? 4. **Quantitative data:** Instances affected (actual vs estimated). Migration completion rate. Support tickets or Slack threads related to the change. 5. **Qualitative data:** If quantitative isn't available: "three teams asked the same question about X", "one team skipped the codemod and manually updated", "unexpected platform dependency broke the migration". 6. **Communications received:** Which channels reached teams? Did they read the message? Evidence: Slack emoji reactions, email click-through rates, questions showing people didn't read. 7. **Support load:** How many questions in Slack? Escalations? Pattern categories (e.g., "5 questions about X", "2 teams didn't know about the codemod"). 8. **Unplanned events:** Platform changes, team reorganizations, urgent hotfixes, or other novel circumstances that affected the release.

Steps

**Step 1: Gather inputs**

Collect the original plan (pull it directly, don't reconstruct from memory). Ask system owners and team leads: what actually happened? If you find disparities between the plan and what people remember, note them — that's a communication gap.

Output: A folder or Slack thread with the original plan, timeline notes, and team feedback.

**Step 2: Extract the blast radius dimension**

Compare estimate vs actual.

**Blast radius accuracy**

Planned: [X affected consumers, Y estimated instances]
Actual: [A affected consumers, B actual instances]
Gap: [Describe variance — larger, smaller, different teams]

Gap classification: 
  - [ ] Foreseeable — more thorough analysis would have caught this
  - [ ] Unforeseeable — novel circumstance (team reorganization, platform change)
  - [ ] Process — analysis was right, execution diverged (e.g., team didn't update)

Specific gaps:
- [List 1-3 unexpected impacts]

Insight: [One sentence — what should we have known or asked?]

**Step 3: Extract the communication dimension**

Assess message clarity and reach.

**Communication effectiveness**

Planned channels: [Slack #channel, email, async standup, office hours, etc.]
Actual reach: [% of teams knew before migration deadline, evidence: emoji reactions, replies, etc.]

Gap: [Did teams miss the message? Was it unclear? Did timing matter?]

Gap classification:
  - [ ] Foreseeable — communication plan was incomplete
  - [ ] Unforeseeable — novel (email landed in spam, team lead OOO at critical moment)
  - [ ] Process — communication was sent but not read or acted on

Specific gaps:
- [List examples: "Team X didn't see the Slack message", "Question about X appeared 10 times"]

Insight: [What communication lever do we need next time?]

**Step 4: Extract the migration path dimension**

Where did teams get stuck despite the guide?

**Migration path quality**

Planned: [Codemod available? Manual steps? Estimated time to update per team?]
Actual: [Did teams run the codemod? Manual updates? Time to complete?]

Gap: [Missing edge cases? Codemod incomplete? Guide unclear?]

Gap classification:
  - [ ] Foreseeable — guide could have covered this
  - [ ] Unforeseeable — novel usage pattern not in our control
  - [ ] Process — guide was clear but not followed

Specific gaps:
- [List 1-3 edge cases or friction points]
  Example: "Teams with custom webpack configs couldn't run the codemod"
  Example: "Migration guide didn't explain how to handle the breaking prop change in unit tests"

Insight: [What process or documentation change prevents this next time?]

**Step 5: Extract the timeline dimension**

Did the release stay on schedule?

**Timeline adherence**

Planne