jaisonerick/run-retrospective

Your output: documentation fixes (some on disk, some in Linear), topic-based lesson files in the knowledge base's docs/ (or equivalent), and proposed skill / CLAUDE.md improvements.

The retrospective itself stays on disk — Linear holds the execution unit, the knowledge base holds the durable record.

Linear contract

Scripts live in ${CLAUDE_PLUGIN_DIR}/scripts/linear/. Required: LINEAR_API_KEY. If it isn't set, fetch it from 1Password: export LINEAR_API_KEY="$(op read op://Environments/Linear/credential)".

This skill reads from Linear (story comments, validation report) and writes a single back-link comment on the spec issue at the end. All other writes are to the disk knowledge base.

Phase 0 — Resolve the spec issue

node "${CLAUDE_PLUGIN_DIR}/scripts/linear/resolve-spec.js" "<identifier>" --require-spec-label

Capture: issue.identifier, issue.url, project.id, project.name, project.documents, issue.description, sub-issues.

Phase 1 — Locate the Knowledge-Base Destination

The retrospective lives on disk. Find where:

1. Read the Linear project description's Context: line — this is the path on disk to the project briefing (e.g. ~/code/jaisonerick/second-brain/engagements/dinie/).
2. The convention (per linear-workflow/docs/approach.md) is:
   • Engagements with OS structure: <engagement>/<os>/retrospectives/spec-vX.Y.md
   • Ventures / studio: <project>/retrospectives/spec-vX.Y.md
3. If the convention does not fit cleanly (no obvious OS folder, etc.), ask the user via AskUserQuestion for the destination path. Never guess.
4. Check whether the file already exists — if yes, ask whether to overwrite or amend.

Phase 2 — Collect Evidence

Gather all sources of truth about what happened during this spec:

1. Story sub-issues + comments — for each sub-issue from resolve-spec.js, fetch:

   node "${CLAUDE_PLUGIN_DIR}/scripts/linear/get-issue.js" "<story-id>" --with-comments
   

   Look in the comments for ## Execution Log blocks: Issues Encountered, Struggled With, Decisions Made.
2. Validation Report Project Document — read its content for failures, fix cycles, DX findings, struggles.
3. Spec architecture document (Spec vX.Y — Architecture) — for the original plan against which to detect drift.
4. Code repository commit history (if a code project) — git log --oneline for the spec's timeframe; look for fix commits, reverts, multiple attempts.
5. Current skills — ${CLAUDE_PLUGIN_DIR}/skills/*/SKILL.md for context on what agents are told to do.
6. CLAUDE.md — current project conventions.

Phase 3 — Identify Patterns

Categorize findings into four buckets:

A. Documentation Drift

Spec architecture says X, but the actual code does Y. Examples:

• Port numbers differ between architecture and config
• Data model has fields the architecture doesn't mention
• API contracts changed during implementation

B. Struggle Patterns

Things that took multiple attempts. Sources:

• Validation re-run cycles (how many rounds? what kept failing?)
• Story execution-log comments with "Struggled With" or repeated "Issues Encountered"
• Commit history showing fix-after-fix patterns

C. Agent Autonomy Gaps

Places where agents couldn't proceed without help:

• AskUserQuestion calls (what did agents not know?)
• Tool errors (what tools failed and why?)
• Validation DX findings (environment/setup issues agents hit)

D. Skill Gaps

Recurring issues that skills should prevent:

• Patterns that could be added to engineer/qa/orchestrate skills
• Missing conventions in CLAUDE.md
• Common mistakes agents keep making

After listing ALL findings across all four categories:

1. Prioritize by impact (how much time was wasted? how likely to recur?)
2. Pick the top 3-5 findings to preserve as lessons. Not everything needs documentation — focus on high-impact, likely-to-recur items.

Phase 4 — Write the Retrospective File on Disk

Write the file to the destination determined in Phase 1:

---
title: "Retrospective — <Project> Spec vX.Y"
created: <date>
updated: <date>
type: retrospective
spec: <DIN-XXX URL>
---

# Retrospective — <Project> Spec vX.Y

## Outcome

One paragraph: what shipped, what didn't.

## Timeline

- Architecture: <date>
- Stories created: <date>
- First validation: <date>
- Spec shipped: <date>

## What worked

- ...

## What didn't

- ...

## Top findings

### 1. <Finding title>
<What went wrong, 1-2 sentences>
<What works and how to prevent it, 1-2 sentences>
<Source: validation TC-XXX, story DIN-YYY comment, etc.>

### 2. ...

## Documentation fixes applied

- <doc/file>: <what was fixed>

## Skill improvements proposed

- <skill name>: <change>

Phase 5 — Update Documentation (No Approval Needed)

Fix factual discrepancies between documentation and reality. These are corrections, not opinions:

1. Spec architecture document on Linear — fix incorrect ports, endpoints, data models, configuration values that don't match the actual code:

   cat /tmp/linear-spec/<spec-id>/architecture-fixed.md | \
     node "${CLAUDE_PLUGIN_DIR}/scripts/linear/update-document.js" "<arch-doc-id>"
   

2. Sub-issue states — if any story sub-issue still has the wrong state (e.g. left in In Progress after merge), transition it now:

   node "${CLAUDE_PLUGIN_DIR}/scripts/linear/transition-issue.js" "<story-id>" --state "Done"
   

3. Knowledge-base briefing — if the project briefing on disk still references the spec as "in flight", update it.

Keep changes minimal and factual. Don't rewrite sections — fix specific inaccuracies.

Phase 6 — Lessons Learned & Skill Improvements (Requires Approval)

For each category below, present findings to the user via AskUserQuestion and only proceed with approved changes.

A. Write Lessons to docs/ Files (knowledge base)

Create or update topic-based files under the knowledge-base docs/ folder (or its equivalent — confirm with the user). Each file covers one topic and can contain multiple findings.

File format:

# <Topic>

## <Finding title>
<What went wrong, 1-2 sentences>
<What works and how to prevent it, 1-2 sentences>

## <Finding title>
...

Rules:

• Append to existing files when the topic already has a docs/<topic>.md file
• Create new files only when no existing file covers the topic
• Keep each finding to 2 paragraphs max (what went wrong + what works)

Before writing, ask the user (via AskUserQuestion):

"I found these lessons worth documenting. Which should I save?"

B. Propose Skill Changes

Group proposed changes by skill file. For each:

1. Describe what happened (the struggle or gap)
2. Show the proposed addition/change (as a diff or new section)
3. Ask the user via AskUserQuestion whether to apply

C. Propose CLAUDE.md Additions

Only for truly universal conventions that apply across ALL specs. These should be rare.

Present each proposed addition and ask via AskUserQuestion before adding.

Phase 7 — Comment Back-Link on the Spec Issue

Post a comment on the spec issue linking the retrospective on disk:

cat <<MD | node "${CLAUDE_PLUGIN_DIR}/scripts/linear/post-comment.js" "<spec-identifier>"
**Retrospective written** — <date>

Path: \`<absolute path to retrospective on disk>\`

Top findings:
1. <finding 1>
2. <finding 2>
3. <finding 3>
MD

Phase 8 — Transition the spec issue to Done

If the user already signed off on the spec, transition the issue to Done (if not already):

node "${CLAUDE_PLUGIN_DIR}/scripts/linear/transition-issue.js" "<spec-identifier>" --state "Done"

Phase 9 — Summary & Commit

1. Summarize what was done:
   • Retrospective file written to disk
   • Documentation fixes applied (Phase 5)
   • Lessons written to knowledge-base docs/ (Phase 6A)
   • Skill changes applied (Phase 6B)
   • CLAUDE.md updates (Phase 6C)
   • Spec issue transitioned and back-link comment posted
2. Commit disk changes with a descriptive message:

   Retrospective: <project> spec vX.Y — N lessons, M doc fixes, K skill updates
   

3. Report to the team lead (if running as a team member) via SendMessage:
   • Summary of findings
   • Files created/modified (disk + Linear)
   • Any deferred items that need manual attention