---
name: ao-retrospective
description: "Scan the current chat session for durable learnings (clarifications, corrections, decisions, pitfalls) and update .agent/ops/memory.md. Use after critical review and before concluding work."
category: core
invokes: [ao-state, ao-task]
invoked_by: []
state_files:
  read: [constitution.md, memory.md, focus.json, issues/*.md]
  write: [memory.md, focus.json, issues/*.md]
references: [.ao/references/confidence.md]
---

# Retrospective / Learning workflow (mandatory)

> **Confidence Reference**: This skill uses canonical confidence definitions from [.ao/references/confidence.md](.ao/references/confidence.md). Retrospective is MANDATORY for low-confidence work, recommended for normal, optional for high.

## Confidence Mismatch Scan (MANDATORY)

During retrospective, explicitly scan for confidence mismatches and record findings in `.agent/ops/memory.md`:

### What to Check
| Pattern | Indicates | Action |
|---------|-----------|--------|
| High confidence + regressions | Over-confidence | Record "Consider marking similar issues as normal confidence" |
| Low confidence + smooth completion | Under-confidence | Record "This pattern may use normal confidence next time" |
| Normal confidence + multiple iterations | Scope misjudged | Record "Break into smaller issues or mark as low" |
| Quickfix used for complex change | Process bypass | Record "Quickfix inappropriate for this type of change" |

### Memory Entry Format
```markdown
## Confidence Learning [{date}]
- Issue: {ID}
- Original confidence: {level}
- Outcome: {what happened}
- Learning: {what to do differently}
```

## Per-Issue Lesson Capture (MANDATORY)

**Before writing to memory.md, capture learnings on each issue worked in this session.**

For each issue in the current iteration batch:

1. Identify learnings relevant to that specific issue (pitfalls, gotchas, decisions, corrections)
2. Call `ao lesson add ISSUE_ID "learning description"` for each one
3. Don't worry about duplicates — just add every learning
4. Lessons are lightweight one-liners, not essays

```bash
# Example: capture lessons discovered during FEAT-0042
ao lesson add FEAT-0042@abc123 "msgspec Struct fields with defaults must come after required fields"
ao lesson add FEAT-0042@abc123 "Typer sub-app needs explicit help text or it inherits parent"
ao lesson add FEAT-0042@abc123 "Golden fixture test broke because new field changed serialization output"
```

**Lessons vs Memory:**
- `ao lesson add` → per-issue learnings (specific to that issue's context)
- `memory.md` → cross-issue learnings (project-wide conventions, patterns)

Both should be updated. Lessons are issue-scoped; memory is project-scoped.

## Goal
Ensure durable, reusable insights from this chat session are captured in `.agent/ops/memory.md` so future sessions can resume without re-discovering them.

## Inputs
- The current chat session transcript (user + assistant messages in this session)
- `.agent/ops/constitution.md`, `.agent/ops/memory.md`, `.agent/ops/focus.json`, `.agent/ops/issues/`

## Extraction rules (strict)
Only capture *durable* items:
- confirmed workflow rules
- stable project conventions (not one-off)
- confirmed commands (but commands/boundaries belong in constitution, not memory)
- user preferences that affect future work on this repo
- corrections to previous misunderstandings
- pitfalls/gotchas discovered during implementation

Do NOT capture:
- transient task state (belongs in focus)
- speculative ideas not adopted
- secrets/tokens
- personal/sensitive data

## Placement rules (strict)
- Project-specific commands/boundaries/constraints → `.agent/ops/constitution.md`
- Durable workflow learnings and recurring conventions → `.agent/ops/memory.md`
- Current session status → `.agent/ops/focus.json`
- Follow-ups and approvals needed → `.agent/ops/issues/`

## Procedure
1) Read: constitution/memory/focus/tasks.
2) Scan the chat session for:
   - explicit corrections ("No, do X instead of Y")
   - newly confirmed commands or tools
   - newly confirmed constraints ("never refactor", "only write docs in …")
   - repeated misunderstandings (add a "pitfall to avoid")
   - preferences expressed by the user
3) **Capture per-issue lessons (MANDATORY):**
   - For each issue worked in this session:
     - Identify pitfalls, gotchas, decisions, corrections specific to that issue
     - Run `ao lesson add ISSUE_ID "learning"` for each one
     - At minimum, reflect on: "What would I tell the next agent working on a similar issue?"
   - If no learnings found, that's OK — but the reflection step is mandatory
4) Update `.agent/ops/memory.md`:
   - append a dated subsection: `## Retrospective YYYY-MM-DD`
   - add short, atomic bullets phrased as "Do/Don't/Prefer"
   - avoid duplication with constitution (link to constitution section if needed)
5) Update focus if the retrospective reveals unresolved items.
6) Invoke `ao-task` discovery if actionable items found.
7) Do not declare completion unless retrospective has been run.

## Issue Discovery During Retrospective

**After scanning session, invoke `ao-task` discovery for actionable items:**

1) **Collect actionable learnings:**
   - "We should add tests for X" → `TEST` issue
   - "This pattern is confusing, needs docs" → `DOCS` issue
   - "Found a bug but didn't fix it" → `BUG` issue
   - "This could be optimized later" → `PERF` issue
   - "Technical debt noticed" → `CHORE` or `REFAC` issue
   - "Security concern noted" → `SEC` issue

2) **Present to user:**
   ```
   📋 Retrospective identified {N} actionable items:
   
   Medium:
   - [DOCS] Document the retry mechanism in PaymentService
   - [TEST] Add integration tests for new OAuth flow
   
   Low:
   - [CHORE] Clean up commented-out code in UserController
   - [PERF] Consider caching user preferences (noted during implementation)
   
   Create issues for these? [A]ll / [S]elect / [N]one
   ```

3) **After creating issues:**
   - Mark in memory.md: "Created {ISSUE-IDs} for follow-up"
   - These become part of the project backlog
