Skip to content

TeamRetroHQ/teamretro-skills / skills/ai-session-retro

ai-session-retro

Verified

Use when a working session with an AI is wrapping up and should be reviewed and logged — "run a retro on this session", "AI session retro", "debrief this session", "log this session" — or when asked to retro a past session from a transcript. Offer it proactively at the natural end of a large or multi-step session. Do NOT use this to create or facilitate a retrospective in a retrospective product (TeamRetro or similar) — this skill reviews AI working sessions only.

# Setup — making capture deterministic

The skill's weakest point is that invocation is probabilistic: if nothing triggers the retro, the log starves silently and the first brief never has enough to say. The fix is to layer a **deterministic trigger** (hook or command) with the **skill as payload** and a **convention line** as the norm. Pick at least one trigger below; two is better.

## 1. Session-start reminder (hook — fires every session)

Claude Code: add to `.claude/settings.json` (project) or `~/.claude/settings.json` (personal):

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Team practice: at the natural end of a substantial session, run the ai-session-retro skill and commit the entry.'"
          }
        ]
      }
    ]
  }
}
```

The hook's output is injected as session context — the agent starts every session already knowing the practice exists. Blunt (it fires on two-minute sessions too), but it's the only trigger that depends on nobody remembering anything.

## 2. End-of-session command (deliberate trigger)

Claude Code: create `.claude/commands/retro.md`:

```markdown
Run the ai-session-retro skill on this session. Follow it exactly: review the actual
session, label each friction item from the fixed vocabulary, propose a ticket-sized
fix with an altitude tag, commit the entry, then show it to me.
```

Typing `/retro` at the end of a feature branch or a triage shift invokes the skill on demand. Deterministic once typed; the weak link is human memory — pair it with trigger 1 or 3.

## 3. Convention line (travels with the scope)

Add one line to the scope's context file (`CLAUDE.md` / `AGENTS.md`) or, for non-code scopes, to the team SOP / workspace instructions:

```
End every substantial AI-assisted session by running ai-session-retro and committing the entry.
```

Zero infrastructure. It decays as the file grows, so treat it as the norm layer, not the trigger.

## 4. Your first entry (what good looks like)

```markdown
# 2026-07-16 — Monthly ads account review

**Session size:** ~25 turns, 1 deliverable
**Outcome:** shipped
**Skill:** ai-session-retro v2.1

## Went well
- Exec summary shipped in one pass; the account structure doc from last month held up

## Friction
- **[missing-context]** The brief didn't say the French campaigns were deliberately
  paused for Q3; ~40 min (est.) auditing a "broken" campaign that was fine.
  → Fix (altitude: process): add campaign-status flags to the monthly brief template

## Guesses made
- Assumed the target CPA unchanged from June — unverified

## Do this first
Campaign-status flags in the brief template — kills the largest single time sink this month.
```

Notes: exactly one label per finding; evidence with a cost (`(est.)` when soft); a ticket-sized fix with an altitude; nothing that identifies a person; no secrets, keys, or customer data (see the skill's never-log list).

## 5. Where the log lives

At the work's **review scope** — the boundary where fixes land. Repo for most dev work (`docs/ai-retros/entries/`). For non-code scopes (an ads account, a support inbox, a client engagement): the same folder structure in that workspace's document home. One log per scope; identical schema everywhere — the schema, not the storage, is what makes entries aggregate later.

After ~5 entries, run the companion `ai-retro-brief` skill before your team's next retrospective.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall