Release Retrospective

Release retrospective

Before you begin: verify references

Confirm that every path in this skill's frontmatter references: exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example npx skills install) dropped the repo-root knowledge-notes/ directory. Tell the user to reinstall by a method in 1-INSTALL.md and run verify-install.sh from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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

The release plan is a hypothesis; the retrospective tests it. Plans usually break on five dimensions: blast radius, communication, migration path, timeline and support burden. For each gap, the useful question is whether better analysis would have caught it or whether it was genuinely novel.

The plan was made with incomplete information. The retrospective reveals what was missing. That gap is the insight, not a failure.

Every figure in the retrospective comes from the plan, a tool result or the user. Where a dimension has no data, write "not measured" rather than estimating it. Never estimate reach or completion percentages.

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

Request the original plan (deprecation plan, migration guide, communication package or decision record) and the execution data listed above. Don't reconstruct the plan from memory or from what you think it probably said; if the user can't supply it, say the comparison is against their recollection and label it that way.

Step 1b: Measure what the repository can tell you

Before asking for figures, take the ones git and a search can give:

• Timeline: git tag --list --format='%(refname:short) %(creatordate:short)' for when the release actually shipped, against the plan's dates
• Migration completion: the deprecation plan's usage commands (rg for the old component, token or prop) run now over the consumers in reach give the count of references still on the old API; run the same over the plan's baseline commit (git log -1 --before=<announcement>) for the starting count. "Completion" is those two counts, not a percentage estimate
• Consumer activity: git log --since=<announcement> --oneline -- <consumer paths> shows when each consumer migrated, and whether anyone touched the codemod's output by hand

Anything the repository can't show (support load, who read the announcement) comes from the user or is "not measured".

Step 2: Compare plan and reality, dimension by dimension

For each dimension where you have data, fill this template once:

**[Dimension]**

Planned: [from the plan]
Actual: [from execution data, or "not measured"]
Gap: [what differed]
Class: Foreseeable / Unforeseeable / Process
Specific gaps: [1–3 items, each with its evidence]
Insight: [one sentence: what should we have known, asked or done?]

Prompts per dimension:

• Blast radius: consumers and instances affected, planned vs actual; unexpected impacts
• Communication: channels planned vs used; evidence teams saw it before the deadline (replies, questions that show they didn't); unclear or badly timed messages
• Migration path: codemod and manual steps planned vs what teams actually did; edge cases the guide or codemod missed
• Timeline: planned milestone dates vs actual; cause of each slip or acceleration
• Support burden: support approach planned vs actual load; question patterns by category, not just totals