swain-retro

What this skill does

<!-- swain-model-hint: sonnet, effort: medium -->

# Retrospectives

<!-- session-check: SPEC-121, SPEC-234 -->
Before proceeding, check for an active session and determine which evidence source to use:

```bash
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
session_check=$(bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null)
session_status=$(echo "$session_check" | jq -r '.status // "none"')

if [ "$session_status" = "active" ]; then
  echo "Using active session evidence"
else
  echo "No active session — falling back to git log evidence"
  git_evidence=$(git log --oneline -20 2>/dev/null)
  echo "Recent commits:"
  echo "$git_evidence"
fi
```

If no active session, proceed with the retro using git log as the primary evidence source. Produce a standalone retro document in `docs/swain-retro/` rather than embedding in an artifact. Adapt reflection questions to the unscoped context.

Captures learnings at natural completion points and persists them for future use. This skill is both auto-triggered (EPIC terminal transition hook in swain-design) and manually invocable via `/swain-retro`.

## Output modes

| Scope | Output | Rationale |
|-------|--------|-----------|
| **EPIC-scoped** (auto or explicit) | `## Retrospective` section appended to the EPIC artifact | The EPIC already contains lifecycle, success criteria, and child specs — it's the single source of truth for "what we shipped and what we learned" |
| **Cross-epic / time-based** (manual) | Standalone retro doc in `docs/swain-retro/` | No single artifact owns the scope — a dedicated doc is required |

## Invocation modes

| Mode | Trigger | Context source | Output | Interactive? |
|------|---------|---------------|--------|-------------|
| **Auto** | EPIC transitions to terminal state (called by swain-design) | The EPIC and its child artifacts | Embedded in EPIC | No — fully automated |
| **Interactive** | EPIC transitions to terminal state during a live session | The EPIC and its child artifacts | Embedded in EPIC | Yes — reflection questions offered |
| **Manual** | User runs `/swain-retro` or `/swain retro` | Recent work — git log, closed tasks, transitioned artifacts | Standalone retro doc (required) | Yes |
| **Scoped** | `/swain-retro EPIC-NNN` or `/swain-retro SPEC-NNN` | Specific artifact and its related work | Embedded in EPIC (if EPIC-scoped) or standalone | Yes |

**Terminal states** that trigger auto-retro: `Complete`, `Abandoned`, `Superseded`. The retro content adapts to the terminal state — an Abandoned EPIC's retro focuses on why work stopped and what was learned, not on success criteria.

## Step 1 — Gather context

Collect evidence of what happened during the work period.

### For EPIC-scoped retros (auto or scoped)

```bash
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
# Get the EPIC and its children
bash "$REPO_ROOT/.agents/bin/chart.sh" deps <EPIC-ID>

# Session log — the primary evidence source for retros (ADR-015)
# Contains decisions, pivots, rationale, and operator feedback
cat .agents/session.json 2>/dev/null | grep -i "<EPIC-ID>\|<SPEC-IDs>"
```

Also read:
- The EPIC's lifecycle table (dates, duration)
- Child SPECs' verification tables (what was proven)
- Any ADRs created during the work
- Git log for commits between EPIC activation and completion dates

**Note (ADR-015):** Do not use tickets (`tk` / `.tickets/`) as retro evidence. Tickets are ephemeral execution scaffolding — they record task status, not decisions or rationale. The session log (`.agents/session.json` JSONL) captures the actual conversation: what was tried, what pivoted, why, and what the operator said. Build the retro narrative from session logs and git history.

### For manual (unscoped) retros

```bash
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
# Recent git activity
git log --oneline --since="1 week ago" --no-merges

# Session log — primary evidence source (ADR-015)
cat .agents/session.json 2>/dev/null | tail -100

# Recently transitioned artifacts
bash "$REPO_ROOT/.agents/bin/chart.sh" status 2>/dev/null
```

Also check:
- Existing memory files for context on prior patterns
- Previous retro docs in `docs/swain-retro/` for recurring themes

## Step 2 — Generate or prompt reflection

### Auto mode (non-interactive)

When invoked by swain-design during a non-interactive EPIC terminal transition (e.g., dispatched agent, batch processing), **generate the retro content automatically** from the gathered context:

1. Synthesize what was accomplished, what changed from the original scope, and what patterns are visible in the commit/task history
2. For `Abandoned` or `Superseded` EPICs, focus on why the work stopped and what was learned
3. Proceed directly to Step 3 (memory extraction) and Step 4 (write output)

### Interactive mode

When the user is present (live session, manual invocation), present a summary and offer reflection:

#### Summary format

> **Retro scope:** {EPIC-NNN title / "recent work"}
> **Period:** {start date} — {end date}
> **Artifacts completed:** {list}
> **Tasks closed:** {count}
> **Key commits:** {notable commits}

#### Reflection questions

Ask these one at a time, waiting for user response between each:

1. **What went well?** What patterns or approaches worked effectively that we should repeat?
2. **What was surprising?** Anything unexpected — blockers, shortcuts, scope changes?
3. **What would you change?** If you could redo this work, what would you do differently?
4. **What patterns emerged?** Any recurring themes across tasks — tooling friction, design gaps, communication patterns?

Adapt follow-up questions based on user responses. If the user gives brief answers, probe deeper. If they're expansive, move on.

## Step 3 — Distill learnings

After the reflection conversation, persist the learnings — but **where** they go depends on whether this is the swain project itself or a consumer project that uses swain.

### Detect context

```bash
# Check if the current repo IS swain (the tool itself)
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
if git remote get-url origin 2>/dev/null | grep -q "cristoslc/swain"; then
  echo "SWAIN_REPO"
else
  echo "CONSUMER_PROJECT"
fi
```

### In consumer projects: write to memory

Learnings from consumer projects go into Claude memory files because they represent operator preferences and project-specific patterns that should persist across sessions.

#### Feedback memories

For behavioral patterns and process learnings that should guide future agent behavior:

```markdown
---
name: retro-{topic}
description: {one-line description of the learning}
type: feedback
---

{The pattern or rule}

**Why:** {User's explanation from the retro}
**How to apply:** {When this guidance kicks in}
```

Write to the project memory directory:
```
~/.claude/projects/<project-slug>/memory/feedback_retro_{topic}.md
```

The project slug is the project path with slashes replaced by dashes (e.g., `/Users/cristos/Documents/code/myapp` → `-Users-cristos-Documents-code-myapp`). These files live in Claude's memory system (not swain's `.agents/` state), which is intentional — retro learnings persist across all Claude Code sessions for this project.

Update `MEMORY.md` index.

#### Project memories

For context about ongoing work patterns, team dynamics, or project-specific learnings:

```markdown
---
name: retro-{topic}
description: {one-line description}
type: project
---

{The fact or observation}

**Why:** {Context from the retro}
**How to apply:** {How this shapes future suggestions}
```

#### Rules for memory creation

- Only create memories the user has explicitly validated during the reflection
- Merge with existing memories when the learning extends a prior pattern
- Use absolute dates (from the retro context), not relative
- Maximum 3-5 memory files per retro — distill, don't dump

### In the swain repo: propose artifacts, not memory

When the retro is running inside swain itself