Add Retro

---
name: add-retro
description: "[ADD v0.11.0] Run a retrospective — context-aware, data-driven review with pre-populated tables"
argument-hint: "[--agent-summary] [--since YYYY-MM-DD] [--scope feature|sprint|session] [--dry-run]"
---

<!-- ADD AskUserQuestion shim (Codex) -->
<!-- Injected by scripts/compile.py when skill-policy.yaml marks a skill -->
<!-- with requires_askuser_shim: true. See AC-026/027/028 in -->
<!-- specs/codex-native-skills.md. -->

> **Codex interaction mode notice (ADD)**
>
> This skill depends on structured question/answer turns. Behavior depends on
> Codex's current mode:
>
> - **Plan mode:** call the `ask_user_question` tool for each prompt below.
>   One question per call. Wait for the user's answer before moving on.
> - **Default mode (no `ask_user_question` available):** emit the questions
>   inline as a numbered list, then **halt and wait** for the user's next
>   prompt. Do **not** improvise, infer, or fabricate answers — this skill
>   fails closed if required input is missing. Resume only after the user
>   replies.
>
> The skill body below defines what to ask; the shim only governs *how* to ask.

---

# ADD Retro Command v0.11.0

Context-aware retrospective that auto-gathers data, classifies human directives and agent observations into scoped tables, and presents pre-populated findings for the human to refine — not recall from scratch.

Two modes:
- **Interactive retro** (default) — Data-driven review with pre-populated tables
- **Agent summary** (`--agent-summary`) — Quick non-interactive observations review

## Pre-Flight

1. Read `.add/config.json` for project context (name, maturity, stack)
2. Read all 3 knowledge tiers:
   a. **Tier 1:** Read `~/.codex/add/knowledge/global.md`
   b. **Tier 2:** Read `~/.claude/add/library.json` (fall back to `library.md`)
   c. **Tier 3:** Read `.add/learnings.json` (fall back to `learnings.md`)
3. Read `~/.claude/add/profile.md` if it exists
4. Determine the retro window:
   - If `--since` provided, use that date
   - If previous retro exists in `.add/retros/`, use that date as start
   - Otherwise, use project creation date from config
5. Check for session handoff — per the Session-Handoff Preflight in `~/.codex/add/references/skill-epilogue.md`

---

## Mode 1: Interactive Retro (default)

### Phase 1: Detect Session Context

Determine how the human spent the retro window:

1. **Read `.add/away-logs/`** — count away sessions, total autonomous hours
2. **Read git log** — count commits, branches, PRs merged
3. **Read `.add/handoff.md`** — check for interactive session indicators
4. **Classify context:**
   - **Autonomous:** >70% of retro window was away-mode sessions
   - **Collaborative:** <30% away-mode, active interactive exchanges
   - **Mixed:** between 30-70% away-mode

The context classification affects the flow:
- **Autonomous:** Human has less context → skip "what went well", reduce questions
- **Collaborative/Mixed:** Full question set

### Phase 2: Auto-Gather Metrics

Collect data for the retro window from all sources:

- **Git log:** commit count, branches merged, PRs
- **Specs:** count completed (status: Complete) in `specs/`
- **Learnings:** count new entries in `.add/learnings.json` since last retro (by date field)
- **Workstation learnings:** count new entries in `~/.claude/add/library.json` since last retro
- **Observations:** read `.add/observations.md` entries since last retro
- **Away logs:** count sessions, total duration from `.add/away-logs/`
- **Handoff:** current state from `.add/handoff.md`

Present the summary:

```
RETROSPECTIVE — {PROJECT_NAME}
Period: {start_date} → {today}
Context: {Collaborative|Autonomous|Mixed} ({detail})

During this period:
  Specs completed: {N}
  Commits: {N}
  Agent learnings recorded: {N} ({N} project, {N} workstation)
  Human directives captured: {N}
  Away-mode sessions: {N}
```

### Phase 3: Human Directives (Table 1)

Extract directives the human gave during the retro window from:
- **Handoff files** — decisions, explicit instructions
- **Learnings entries** with `classified_by: "human"` — human-reclassified knowledge
- **`.add/observations.md`** — entries recording human feedback or directives
- **Conversation context** — explicit instructions from the current or recent sessions

For each directive, **classify scope:**

| Scope | Signal |
|-------|--------|
| project | References specific files, config, routes, schemas unique to this project |
| workstation | References tools, libraries, workflows that apply across projects |
| organization | References team, org, or company patterns (stub — accept but note "future tier") |
| community | References universal methodology insights (stub — accept but note "future tier") |

**If no directives found:** Skip Table 1 entirely, move to Phase 4. Do not show an empty table.

**If directives found:** Present:

```
In our recent sessions, you provided some key insights:

━━━ TABLE 1: YOUR DIRECTIVES ━━━
| # | Directive | Scope | Source |
|---|-----------|-------|--------|
| 1 | {directive text} | {scope} | {source} |
| 2 | {directive text} | {scope} | {source} |

Are these captured correctly in learnings? Any to add, remove, or reclassify?
```

Wait for human confirmation. Apply any changes to learnings JSON files.

### Phase 4: Agent Observations (Tables 2 & 3)

Read agent-generated entries since last retro:
- **Table 2 (Project):** Entries from `.add/learnings.json` where `classified_by: "agent"` and `date` within retro window
- **Table 3 (Workstation):** Entries from `~/.claude/add/library.json` where `classified_by: "agent"` and `date` within retro window

**Skip any table that has zero entries.** Do not show empty tables.

**ADD Methodology Adherence Self-Assessment:**

Include in the agent observations a self-assessment of how well ADD methodology was followed during the retro window. Check each rule:

| Rule | How to Assess |
|------|---------------|
| Spec-before-code | Were any features implemented without a spec? Check git log for implementation commits vs spec dates |
| TDD cycles | Were tests written before implementation? (N/A for markdown-only plugins) |
| Auto-handoffs | Were handoffs written after commits and major work? Check `.add/handoff.md` timestamps vs git log |
| Learning checkpoints | Were learnings recorded at trigger points (post-verify, post-tdd, post-deploy, post-away)? Count expected vs actual |
| Quality gates | Were `/add-verify` runs done? Did they pass first time? |
| Source control | Were conventional commits used? Check last N commits for pattern compliance |

Format methodology adherence as a **table** (not inline checkmarks — tables are easier to scan):

```
━━━ TABLE 2: AGENT OBSERVATIONS (PROJECT) ━━━
| # | Observation | Severity |
|---|-------------|----------|
| 1 | {observation} | {severity} |

ADD Methodology Adherence:
| Rule | Status | Detail |
|------|--------|--------|
| Spec-before-code | ✓ Pass | {assessment} |
| Auto-handoffs | ✓ Pass | {assessment} |
| Learning checkpoints | ✗ Fail | {assessment with specifics} |
```

**Do NOT show Table 3 if it has zero entries.** Skip it silently — no heading, no empty table, no mention.

Then ask:

```
Help me polish these. Do you disagree or wish to modify any of these learnings?
```

Wait for human input. If the human identifies data gaps (missing checkpoints, incorrect entries), fix them **in the background** — queue the writes and continue the retro flow immediately. Do not block the human while writing JSON entries or regenerating markdown views.

### Phase 5: Targeted Questions

Ask one at a time. Adapt based on session context:

**Q1 (skip if Autonomous context):** "What went well?"
→ Only ask if the human had enough interactive context to answer meaningfully.

**Q2:** "What needed improvement that was not included already in our learnings?"
→ Scoped to gaps — the tables already surfaced known issues.

**Q3 (rate-limited — 1x per calendar day):** "On a scale of 0.0 to 9.0, how well are we working together?"
→ To check rate limit: read `.add/retros/` for any file matching `retro-{today's date}*.md` that already has a `Human Collaboration` score populated. If found, skip this question.

**Q4 (rate-limited — 1x per calendar day):** "Any improvements for Agent Driven Development you would suggest?"
→ Same rate-limit check as Q3. These two are always asked/skipped together.

### Phase 6: Agent Self-Assessment Scores

The agent provides two self-assessed scores with evidence. These are NOT asked of the human — the agent generates them from data.

**ADD Methodology Effectiveness (0.0-9.0):**
- Based on methodology adherence from Phase 4
- Consider: spec coverage, TDD compliance, handoff discipline, checkpoint completeness, quality gate usage
- Must cite specific evidence (not vague claims)

**Swarm Effectiveness (0.0-9.0):**
- How well did agents collectively build together?
- Consider: parallel subagent usage, context handoff quality between sessions, duplicate work avoided, session continuity
- Must cite specific evidence

Format:

```
━━━ AGENT SELF-ASSESSMENT ━━━
ADD Methodology Effectiveness: {X.X} / 9.0
  Evidence: {specific evidence from the retro window}

Swarm Effectiveness: {X.X} / 9.0
  Evidence: {specific evidence from the retro window}
```

Scores must be justified by evidence. If the agent detects its own score seems inflated relative to evidence, adjust downward. Honesty over optimism.

### Phase 7: Record and Update

1. **Write retro archive:**
   Use `~/.codex/add/templates/retro.md.template` as structure.
   Write to `.add/retros/retro-{date}.md` (create directory if needed).
   Fill all sections with data from the retro.

2. **Store scores:**
   Read `.add/retro-scores.json` (create from `~/.codex/add/templates/retro-scores.json.template` if doesn't exist).
   Append entry:
   ```json
   {
     "date": "{YYYY-MM-DD}",
     "collab_score": {X.X},
     "add_effectiveness": {X.X},
     "swarm_effectiveness": {X.X},
     "retro_file": ".add/retros/retro-{date}.md",
     "context": "{collaborative|autonomous|mixed}"
   }
   ```
   If collab score was rate-limited (skipped), use `null` for `collab_score`.

3. **Store ADD feedback:**
   If the human provided ADD improvement suggestions, append to `.add/add-feedback.md`:
   ```markdown
   ## {YYYY-MM-DD}
   - **Suggestion:** {text}
   - **Retro:** .add/retros/retro-{date}.md
   - **Streamed:** false
   ```
   Create the file with `# ADD Methodology Feedback` header if it doesn't exist.

4. **Update learnings:**
   Write new learning entries from the retro as structured JSON to the appropriate file (`.add/learnings.json` or `~/.claude/add/library.json`). Follow the checkpoint process in `~/.codex/add/references/learning-reference.md`:
   - Classify scope for each new learning
   - Write to the appropriate JSON file
   - Regenerate the corresponding markdown view

5. **Scope review and reclassification:**
   Review entries classified by agents since the last retro:
   ```
   SCOPE REVIEW — Agent-classified entries since last retro:
     L-{NNN}: "{title}" — classified as {scope} by agent
     WL-{NNN}: "{title}" — classified as {scope} by agent

   Any reclassifications needed?
   ```
   For each reclassification the human approves:
   - Move the entry between JSON files
   - Update `scope` field and `classified_by` to `"human"`
   - Assign new ID appropriate to target file
   - Regenerate both markdown views

   **Auto-promotion proposals (batch):**

   In addition to asking per-entry, scan `.add/learnings.json` entries since the last retro and auto-propose **workstation promotion candidates** — entries that look universal enough to belong in `~/.claude/add/library.json` for cross-project use.

   Promotion signals (ANY of):
   - `severity >= "high"` AND `category = "anti-pattern"`
   - Body contains "always", "never", "every time", "on every", "default" — language indicating a general rule rather than a project-specific fact
   - `stack` entries describe tooling that the user's other projects in `~/.claude/add/projects/` also use (check registry stacks)
   - Body references generic cloud/infra primitives (GCE, AWS, GKE, EKS, ArgoCD, cert-manager, etc.) without project-specific identifiers

   Present the candidates as one batch table:

   ```
   PROMOTION CANDIDATES — cross-project workstation learnings

   | # | Entry | Signal | Promote? |
   |---|-------|--------|----------|
   | 1 | L-{NNN}: "{title}" | {signal that matched} | [y/n] |
   | 2 | L-{NNN}: "{title}" | {signal that matched} | [y/n] |
   ...

   Reply with the numbers to promote (e.g., "1,3,5" or "all" or "none").
   ```

   For each approved promotion:
   - Copy entry to `~/.claude/add/library.json` with a new `WL-{NNN}` ID
   - Set `source` to the project name
   - Set `classified_by` to `"human"`
   - Leave original entry in `.add/learnings.json` (projects may still reference it)
   - Regenerate both markdown views at the end

   Why this exists: the agentVoice retro (2026-04-12) surfaced 8 clearly-universal lessons (ArgoCD, CI-disabled, Cloud Build, WebSocket timeout, E2E skip ban) that sat in project markdown for 40 days without promotion. A batch proposal at retro time closes that gap.

6. **Update cross-project persistence:**
   a. **Profile updates** (`~/.claude/add/profile.md`): If retro reveals preferences that carry to other projects, ask: "Add to your ADD profile?"
   b. **Project index** (`~/.claude/add/projects/{name}.json`): Update `last_retro` date and `learnings_count`.

7. **Promote to plugin-global (ADD dev project only):**
   If running inside the ADD plugin project (detected by `knowledge/global.md` existing as a local file), present Tier 1 promotion candidates.

8. **Apply config/template changes:** If agreed changes affect the process, make edits now.

9. **Deduplicate knowledge stores:**
   Check all stores for duplicates or misplaced entries. Report: "{N} duplicates consolidated, {N} entries relocated."

10. **Prune stale entries:**
    - Observations >30 days old without `[synthesized M-{NNN}]` → archive
    - Learnings >90 days old without references → flag for human review (never auto-delete)

11. **Regenerate markdown views** after all JSON modifications.

### Phase 8: Observation Synthesis

Read `.add/observations.md` and synthesize:

1. Group observations by operation type
2. Identify patterns (3+ similar = a pattern)
3. For each pattern, propose a process mutation:
   ```
   ### Proposed Mutation: {title}
   **Skill:** /add-{skill-name}
   **Change:** {concrete change to the skill}
   **Evidence:** {observation timestamps and summaries}
   **Expected outcome:** {what should improve}
   ```
4. Present proposals to human for approval. Only apply approved mutations.

### Phase 9: Apply Approved Mutations

For each human-approved mutation:
1. Read the target skill's SKILL.md
2. Apply the change
3. Log in `.add/mutations.md`
4. Mark source observations as synthesized

### Phase 10: Process Health Assessment

Review `.add/mutations.md` for previously applied mutations:
1. Did the problem recur? → Strengthen mutation
2. Did the problem stop? → Note positive outcome
3. New side effects? → Adjust mutation
4. Report process health summary

### Phase 11: Maturity Promotion Assessment

If the retro surfaces a promotion request, run an evidence-based check. See maturity promotion criteria:

**POC → Alpha:** At least 3 evidence items (specs, tests, CI, commits, etc.) + core concept validated
**Alpha → Beta:** Feature specs exist, coverage >50%, CI/CD configured, PR workflow, 2+ environments, conventional commits, TDD evidence
**Beta → GA:** Coverage >80%, protected branches, release tags, 3+ environments, all gates blocking, 30+ days stability, SLAs defined

Do NOT promote without evidence. Promotion requires proof, not aspiration.

---

## Mode 2: Agent Summary (`--agent-summary`)

Quick, non-interactive mode. Present accumulated observations without a full retro.

1. Read `.add/learnings.json` and `~/.claude/add/library.json`
2. Filter entries since last retro
3. Present structured summary:

```
AGENT OBSERVATIONS — since {last_retro_date}

TECHNICAL DISCOVERIES ({N} entries):
  - {discovery with date}

ARCHITECTURE DECISIONS ({N} entries):
  - {decision with rationale}

ADD METHODOLOGY ADHERENCE:
  {self-assessment checklist}

WHAT WORKED:
  - {positive pattern}

WHAT DIDN'T:
  - {negative pattern}

SUGGESTED CHANGES:
  1. {suggestion with rationale}

These are observations only — no changes applied.
Run /add-retro for a full interactive retrospective.
```

---

## Retro Frequency Guidance

Display during the first retro:

```
RECOMMENDED RETRO CADENCE:
  - Agent auto-checkpoints: Continuous (after each verify, cycle, away session)
  - Agent summary (/add-retro --agent-summary): Weekly or before planning
  - Full interactive retro (/add-retro): After each feature/sprint completion,
    or every 2 weeks — whichever comes first
```

---

## Score Semantics

All scores use 0.0-9.0 scale with 1 decimal precision:

| Range | Meaning |
|-------|---------|
| 0.0-2.0 | Poor — process not working, significant friction |
| 2.1-4.0 | Below average — notable gaps, frequent workarounds |
| 4.1-6.0 | Adequate — functional but room for improvement |
| 6.1-8.0 | Good — effective with minor issues |
| 8.1-9.0 | Excellent — highly effective, minimal friction |

---

End-of-skill epilogue: follow `~/.codex/add/references/skill-epilogue.md` (observation + learning checkpoint + progress tracking). The retro's Phase 7 already records its learnings — do not duplicate them; the epilogue's observation line still applies.