# Retro

> >

- **Type:** Skill
- **Install:** `agentstack add skill-craftwork-design-retro-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [craftwork-design](https://agentstack.voostack.com/s/craftwork-design)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [craftwork-design](https://github.com/craftwork-design)
- **Source:** https://github.com/craftwork-design/retro/tree/main/skill
- **Website:** https://craftwork.design

## Install

```sh
agentstack add skill-craftwork-design-retro-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# retro — turn your agent's failures into harness improvements

You are running a retrospective on how the agent (you) has been performing
for this user, based on their real session transcripts. The goal is not a
report for the sake of a report. The goal is a small number of concrete,
minimal changes to the harness (CLAUDE.md, skills, hooks, permissions,
memory) that would have prevented the friction you find. Evidence first,
changes second.

## Arguments

`$ARGUMENTS` maps to scanner flags:

- `Nd` (e.g. `7d`, `90d`) → `--days N` (strip the `d`)
- `all` → `--all` (omit `--project`)
- they combine: `/retro all 90d` → `--all --days 90`
- no arguments → current project, `--days 30`

## Step 1 — collect signals

Locate the scanner, in order: `${CLAUDE_PLUGIN_ROOT}/scripts/scan.py` (set
when installed as a plugin); `~/.claude/skills/retro/scripts/scan.py`; if
`$CLAUDE_CONFIG_DIR` is set, `$CLAUDE_CONFIG_DIR/skills/retro/scripts/scan.py`;
then `.claude/skills/retro/scripts/scan.py` in the project. Then run it with
an explicit absolute project path (do not rely on the shell's cwd):

```bash
python3 ~/.claude/skills/retro/scripts/scan.py \
  --project "" --days 30 --format json
```

Sanity-check the output before proceeding:

- `project` and `sessions_scanned` look right for this project.
- If the scanner exits with "no transcripts", say so and stop; offer
  `/retro all`.
- If `sessions_scanned` is 0, or it is small and every `totals` value is 0,
  do NOT write a full retro. Tell the user plainly there is not enough
  history here yet, suggest `/retro all` and `/retro 90d`, and stop. A
  hollow zeros-report reads as "broken".
- With fewer than ~3 sessions, don't hunt cross-session patterns (every
  cluster field is empty by construction). Do a single-session post-mortem:
  the one place the agent claimed done-but-wasn't, at most one earned rule,
  and say explicitly this is not a trend.
- If `truncated` is true OR `sessions_scanned` equals `--limit`, the window
  was capped: rerun with `--limit 1000` before doing anything else, or state
  the real coverage in the report header instead of "last N days".
- Sessions are selected by file modification time; individual quotes carry
  their own `ts` and may predate the window. Check the `ts` of every quote
  you cite; present older evidence as such, never as recent.

## Step 2 — read the current harness

Read the project's `CLAUDE.md` (also check `claude.md` / `Claude.md` and
`~/.claude/CLAUDE.md`). You need it to tell which failures happened BECAUSE
a rule is missing, unclear, or being ignored, versus failures no rule could
have prevented.

**Check the rule's age against the failures' dates before you claim "the
rule was ignored".** A rule that already covers a failure has three possible
readings, and they lead to different fixes:

1. The rule predates the failures → it exists but the agent doesn't act on
   it. Fix: harden it into a blocking gate, not a fresh rule.
2. The rule was added *after* the failures (often as a reaction to them) →
   the failures are already addressed; do not re-report them as open.
3. No rule covered it → propose a new rule.

Compare `git log -1 --format=%cI -- CLAUDE.md` (or the file mtime) and, if
you can, `git blame` the specific line against the `ts` of the evidence
quotes. If you cannot establish the order, say so in the report rather than
asserting the rule was ignored.

Note: design-heavy projects often keep CLAUDE.md gitignored. If
`git ls-files --error-unmatch CLAUDE.md` fails, the file is untracked and
`git blame` is unavailable — individual rule ages are unknown. Use
whole-file mtime plus content match only as weak evidence, and never claim a
rule was "ignored" on that basis alone.

If no project CLAUDE.md exists, the Step 4 diff becomes a proposed new file:
say "create `/CLAUDE.md`" and show its full contents. Rules that
describe the user rather than one project (reply language, tone, commit
habits) belong in `~/.claude/CLAUDE.md` — mark those as user-level.

## Step 3 — cluster into patterns

Identify at most 5 recurring patterns. A pattern needs at least 2
independent occurrences (exception below). For each candidate, check the
excerpts yourself: a "correction" flagged by the scanner may be a normal
instruction — drop those.

Start with the highest-yield fields:

- `rule_requests` — the user dictated a rule out loud ("запомни, отныне
  всегда..."). **Exception to the 2-occurrence rule: one rule_request is
  enough** — the user explicitly asked. But read the surrounding transcript
  before converting: reconcile with existing CLAUDE.md content (the literal
  words may contradict a documented legitimate case), and drop entries too
  vague to reconstruct.
- `repeated_instructions` — the same ask across 2+ sessions, with session
  ids and timestamps per example. Each cluster is a *candidate* rule, not a
  rule by definition: reject clusters that are per-task go-ahead commands
  the user must issue deliberately (deploy, "commit this now"), and clusters
  already covered by CLAUDE.md — those become "rule exists but isn't
  followed", which is a different fix (harden the rule into a blocking gate,
  sharpen its wording, or move it higher in the file) — but first confirm
  the rule predates the failures, per Step 2, or you will re-report a fix
  that already landed.
- `admissions` — the agent conceded a mistake; `user_text` holds what the
  user complained about, `admission` often names the root cause.
- `error_loops` — the same tool+target failing 2+ times: the source for
  "wrong default in the harness" patterns (wrong test runner, missing env).
  `retry_loops` is the ≥3-failure subset.
- `nudges` — only per-session counts: filter `sessions[]` for `nudges >= 2`
  (= the agent stalls mid-task). For quotes, grep those transcripts;
  otherwise cite session titles and dates from `sessions[]`.

On design, creative, or writing projects, `redo` and bare comparatives
("shorter", "покороче", "мельче", "переделай хедер") are usually the WORK,
not agent failure — that is just what iteration sounds like. Require an
`after_success_claim`, `frustration`, `failure_report`, or `post_interrupt`
co-tag before counting a `redo`- or `correction`-only entry as a pattern, or
you will over-report friction on creative repos.

To form candidates from the flat `corrections` list: group by recurring
nouns/verbs in `text` and by session overlap with other signals; a candidate
is any theme with 2+ entries. Weigh `reasons` tags in this order (strongest
first):

1. `after_success_claim` — agent said "done/fixed", user came back with a
   failure. Near-certain, and the most expensive kind.
2. `frustration` — the user is visibly angry.
3. `post_interrupt` — Esc + redirect. ~70% are real.
4. `failure_report` — something built or claimed broke.
5. `correction` / `redo` / `repeat_paste` — real but noisier; verify quotes.

Multi-reason entries outrank single-reason ones. Note: the excerpt arrays
are capped (`corrections` 80, `admissions` 40, `sessions` 100 + all
abandoned) — use `totals` for counts, arrays for quotes. Ignore
`top_correction_terms` unless it shows an obvious theme.

If you need more context on a session, its transcript is at
`~/.claude/projects//.jsonl` — grep around
the relevant timestamps; transcripts are large.

## Step 3.5 — fan out to subagents when the report is large

If `totals.corrections + totals.admissions > 40`, or you have 5+ candidate
patterns, do not judge everything in this context — you will skim and miss.
Spawn one verification subagent per candidate pattern (Agent/Task tool, in
parallel). Give each: the pattern name, its excerpts with session ids and
timestamps, the transcript directory path, and this instruction:

> Verify this candidate pattern against the raw transcripts. Return:
> CONFIRMED or REJECTED, the 2 best verbatim quotes with dates, a one-line
> root cause, and a proposed minimal rule. Reject if the quotes read as
> normal instructions rather than friction.

Then judge the returned evidence yourself and keep at most 5 confirmed
patterns. Subagents read transcripts locally; nothing leaves the machine.

## Step 4 — write the retro

Present in chat, in the user's language, in this shape:

```
# Retro:  — 

## Pattern 1:  ( occurrences,  sessions)
Evidence: 1-3 real quotes, each dated (or "N sessions, undated" — never invent dates)
Root cause: one sentence
Fix: the exact change, quoted

... up to 5 patterns, ranked by cost to the user ...

## Proposed changes

## What went well

```

## Step 5 — apply on confirmation

Number every proposed fix and let the user pick (all / numbers / none).
Apply only what they picked. Rules must be short, imperative, and specific
("Run tests with `pnpm vitest run`, never `npm test`"), never vague ("be
more careful with tests").

- Hooks/permissions: do not write settings.json schemas from memory — they
  change between versions. Consult the harness settings docs or the
  update-config skill if available. Prefer project `.claude/settings.json`
  unless the rule is user-wide.
- If the user dictated "remember this" rules, auto-memory files
  (`~/.claude/projects//memory/`) are a valid target alongside
  CLAUDE.md.

## Hard rules

- Never invent evidence. Every quote must come from the scanner output or a
  transcript you actually read; every date from a real `ts`.
- Fewer, sharper findings beat a long list. Zero real patterns is a valid
  outcome — say so.
- Never modify CLAUDE.md, settings, skills, or memory without explicit
  confirmation in this conversation.
- Everything stays local. Never send transcript content to any external
  service.
- Do not treat scanner counts as truth; they are candidates. You are the
  judge.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [craftwork-design](https://github.com/craftwork-design)
- **Source:** [craftwork-design/retro](https://github.com/craftwork-design/retro)
- **License:** MIT
- **Homepage:** https://craftwork.design

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-craftwork-design-retro-skill
- Seller: https://agentstack.voostack.com/s/craftwork-design
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.