run-retrospective

Analyze completed plan artifacts to extract prioritized retrospective findings and proposed documentation changes.

Updated Mar 5, 2026
One-click install
npx skills add https://github.com/jaisonerick/spec-plugin --skill run-retrospective
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: run-retrospective
Source: https://github.com/jaisonerick/spec-plugin/tree/main/plugins/spec-plugin/skills/run-retrospective
Command: npx skills add https://github.com/jaisonerick/spec-plugin --skill run-retrospective

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Post-plan knowledge and process gaps often vanish after a project closes, causing repeated mistakes, documentation drift, and lost learnings; this Skill centralizes evidence and turns plan artifacts into prioritized, actionable lessons and minimal doc fixes so teams capture value from the work they've already done.

Core Features & Use Cases

  • Evidence collection: Reads PROGRESS.md, story execution logs, QA run results, architecture docs, commit history, and current SKILL.md files to build a complete timeline of what happened.
  • Pattern identification: Categorizes findings into documentation drift, struggle patterns, agent autonomy gaps, and skill gaps, then prioritizes by impact and likelihood to recur.
  • Documentation & proposals: Applies factual doc fixes, drafts topic-based lessons in docs/, and prepares proposed skill and CLAUDE.md changes for user approval; commits approved changes and reports the summary to the team.
  • Use case: Run after a plan's QA completes to produce a short, prioritized retrospective, clean up inaccurate docs, and propose targeted skill improvements.

Quick Start

Run the retrospective on plan-0-infrastructure after QA completes to generate prioritized lessons, factual doc fixes, and proposed skill changes for approval.

Frequently Asked Questions about run-retrospective

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a postmortem from completed plan artifacts and git history?

To generate a postmortem, you analyze completed plan artifacts like PROGRESS.md, story logs, and QA results alongside git commit history. This process extracts prioritized retrospective findings, categorizing evidence into documentation drift, struggle patterns, and skill gaps.

What is the best way to fix documentation drift after a software project ends?

Fixing documentation drift involves reading architecture docs and current SKILL.md files to identify inaccuracies, then applying minimal factual doc fixes and drafting topic-based lessons in docs/. The proposed changes are prepared for user approval before committing.

How do I extract lessons learned from QA results and story execution logs?

Extracting lessons learned requires reading story execution logs and QA run results to identify patterns. Findings are categorized into struggle patterns, agent autonomy gaps, and skill gaps, then prioritized by impact and likelihood to recur.

When should I run a retrospective on a finished software plan?

Run a retrospective after a plan's QA completes to examine final artifacts. This timing ensures all execution logs, commit history, and test results are available to consolidate evidence into actionable lessons and proposed skill improvements.

Can I propose updates to CLAUDE.md based on recurring agent autonomy gaps?

Yes, you can propose updates to CLAUDE.md based on identified agent autonomy gaps. The retrospective process prepares proposed skill and CLAUDE.md edits for user approval, generating a commit summary upon acceptance to capture process improvements.