lucasilverentand/retrospecting

Retro

Retrospective analysis of recent agent sessions and code changes to continuously improve the skill library.

Current context

• Branch: !git branch --show-current
• Project: !basename $(git rev-parse --show-toplevel)

Decision tree

• What do you want to do?
  • Full retro (conversations + git) -> follow "Running a full retro" below
  • Just mine conversations -> run tools/conversation-miner.ts --project $(git rev-parse --show-toplevel) and review findings
  • Just check git rework -> run tools/rework-detector.ts and review findings
  • Create skills from findings -> follow "Acting on findings" below

Running a full retro

A full retro has two phases: gathering data and cross-referencing existing skills. For larger skill libraries or longer time ranges, offer to use agents — a Miner to gather and cluster, and a Cross-Referrer to classify findings against existing skills. For smaller retros, single-agent is fine. Let the user decide.

Single-agent flow

1. Gather data

Run both tools in parallel to collect findings:

tools/conversation-miner.ts --project $(git rev-parse --show-toplevel) --days 7 --json
tools/rework-detector.ts --days 7 --json

Adjust --days based on how far back the user wants to look (default: 7 days).

2. Review and cluster

Read the JSON output from both tools. Look for clusters — multiple findings that point to the same underlying issue or preference. Group them by theme:

• Repeated struggles — the same kind of correction or retry across multiple conversations
• Taste patterns — consistent preferences that aren't yet codified in a skill
• Rework hotspots — files or areas where git shows repeated churn alongside conversation struggles
• Skill gaps — tasks that required many turns but could be streamlined with a skill

3. Cross-reference existing skills

Before proposing new skills, check what already exists:

Use Glob to list existing skills:

Glob pattern: plugins/*/skills/*/SKILL.md

For each cluster, search existing skills for overlap:

Grep pattern: "<keyword>" in plugins/*/skills/*/SKILL.md

Classify each cluster as:

• New skill needed — no existing skill covers this area
• Existing skill update — a skill exists but misses this pattern
• AGENTS.md / CLAUDE.md addition — too small for a skill, better as a project instruction
• Memory entry — a personal preference that should be saved to memory

Agent flow (optional)

When the skill library is large or the retro covers many days, agents keep context focused:

Miner (general-purpose agent) — runs both tools, clusters raw findings by theme, produces a structured findings document with clusters, evidence, and frequency counts.

Cross-Referrer (Explore agent, read-only) — receives the Miner's clusters, reads all existing skills in the repo (Glob for plugins/*/skills/*/SKILL.md), searches for overlap, and classifies each cluster as new skill / skill update / project-instructions addition / memory entry. Returns an annotated report.

Flow: spawn Miner → read its clusters → spawn Cross-Referrer with clusters → read its classifications → format the report below.

4. Present the retro report

Present findings to the user as a structured report:

## Retro Report — [date range]

### Struggles Found
For each struggle:
- **Pattern**: what kept going wrong
- **Evidence**: quotes from conversations, git commits
- **Frequency**: how many times it appeared
- **Suggested action**: new skill / skill update / project instructions / memory

### Taste Signals Found
For each taste:
- **Preference**: what the user consistently wants
- **Evidence**: quotes showing the pattern
- **Suggested action**: where to codify this

### Rework Hotspots
For each hotspot:
- **Files**: which files had high churn
- **Pattern**: what kind of rework (fix-after-feat, reverts, etc.)
- **Suggested action**: skill that could prevent this

Wait for user input before acting on any findings.

Acting on findings

For each approved finding:

• New skill -> use the authoring skill to create it. Pass the finding's evidence as context for intent capture — the struggle patterns become the skill's decision tree branches, the taste signals become its conventions.
• Skill update -> read the existing SKILL.md, identify where the new pattern fits, and edit it in. Add new decision tree branches, conventions, or tool behaviors as needed.
• AGENTS.md / CLAUDE.md addition -> append the preference or rule to the project's agent instruction file.
• Memory entry -> save to memory using the appropriate memory type (feedback for corrections, user for preferences).

Key references

|File|What it covers| |---|---| |references/pattern-catalog.md|Catalog of recognizable struggle and taste patterns with detection heuristics|