agentleFS
Gord1yGord1y/countersign-skills/skills/retro/SKILL.md

retro

Skill2 starsChanged 42 days agoMITView on GitHub

Turn a session's or run's mistakes and lessons into structure, not notes. Each lesson goes to the highest rung that works, proven to fail on the real mistake first.

194 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use plan-tune, ios-clean and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ShreyRaviSkill

    plan-tune

    Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences (never-ask / always-ask / ask-only-for-one-way), inspect the dual-track profile (what you declared vs what your behavior suggests), and enable/disable question tuning. Conversational interface — no CLI syntax required.

    Also in 9 projects that use this

  • Saqlain-811Skill

    ios-clean

    Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app. (gstack)

    Also in 5 projects that use this

  • Saqlain-811Skill

    ios-fix

    Autonomous iOS bug fixer. (gstack)

    Also in 5 projects that use this

  • seek888Skill

    pair-agent

    Pair a remote AI agent with your browser. One command generates a setup key and prints instructions the other agent can follow to connect. Works with OpenClaw, Hermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent gets its own tab with scoped access (read+write by default, admin on request). Use when asked to "pair agent", "connect agent", "share browser", "remote browser", "let another agent use my browser", or "give browser access". (gstack) Voice triggers (speech-to-text aliases): "pair agent", "connect agent", "share my browser", "remote browser access".

    Also in 11 projects that use this

  • ShreyRaviSkill

    landing-report

    Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots are currently claimed by open PRs, which sibling Conductor workspaces have WIP work likely to ship soon, and what slot /ship would pick next. No mutations — just a snapshot. Use when asked to "landing report", "what's in the queue", "show me open PRs", or "which version do I claim next". (gstack)

    Also in 8 projects that use this

  • timurgaleevSkill

    document-generate

    Generate missing docs for a feature, module or project as tutorials, how-tos, reference and explanation.

    Also in 7 projects that use this

  • +1 more from Saqlain-811
  • +2 more from ShreyRavi

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 170 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the session in front of you, or the sessions the user names.

    line 28
  2. Distinctive:

    Put each lesson into the highest rung that works.

    line 61
  3. Very specific:

    Keep evidence in writeups/scratch/<date>-retro/.

    line 95
  4. Very specific:

    If local.md exists next to this file, read it.

    line 106

“Common” is measured: kept by at least 6 in 10 of the 170 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Retro

A note in memory may never load, and a model may read it and still slip. A check runs every time. This skill turns what went wrong in a session into the strongest fix the repo can hold, proves the fix catches the real mistake, and never settles for a note.

Repo facts

This skill needs the facts below. Look each one up in the repo's CLAUDE.md (or AGENTS.md) and the files it imports or points to (of a repo-facts file, only this skill's section: sed -n '/^## retro$/,/^## /p' <file>), then in local.md next to this file. If neither has it, ask the user once, then suggest the one line to add to CLAUDE.md so the next run finds it.

FactExample
The gate that must passpnpm check, which runs lint, typecheck and tests
The lint configuration and the test runnereslint.config.js; vitest
The docs per area, and the repo's knowledge indexdocs/features/<name>.md, mapped by docs/knowledge/index.md

Step 1: gather the lessons

Use the session in front of you, or the sessions the user names. Sources, in this order:

  • The live context of this session.
  • Claude Code transcripts: ~/.claude/projects/<key>/*.jsonl, or under $CLAUDE_CONFIG_DIR when it is set. The key is the repo's absolute path with each non-alphanumeric character written as -.
  • Codex transcripts: $CODEX_HOME/sessions/, default ~/.codex/sessions/, files named rollout-*.jsonl.
  • Claude Code's auto memory for the repo, to find what was already written down.

A lesson is a user correction, a failed gate, a revert, a retry repeated, or a fact found late.

With several transcripts, or one over 1 MB, read each in its own reader so the main context stays small. Each reader gets this brief, with the transcript's absolute path filled in:

Read the transcript <absolute path>, a JSONL file, in ranges of 200 lines. Report at most 30
lines of lessons. For each: what went wrong; the evidence, as a transcript line number and at most
two quoted lines; what would have prevented it. Never copy a secret.

Claude Code. One Agent call per transcript, up to four in one message: subagent_type: "researcher" when the researcher agent is installed and "general-purpose" otherwise, model: "haiku", effort: "low", run_in_background: false.

Under Codex there is no Agent tool. Under T3 Code, dispatch each transcript as a delegate_task child with mode: "wait", target: {providerInstanceId: "codex", model: "gpt-6.1-terra", options: {reasoningEffort: "low"}} and the same brief, which starts by telling the child to begin with a fresh context. Without T3 Code, read one transcript at a time yourself, keeping only its report before the next.

Step 2: pick the rung

Put each lesson into the highest rung that works. For each lesson, say in one clause why every higher rung does not work.

RungThe fixChoose it when
1. ArchitectureChange the structure so the mistake cannot be written.The code offers two ways to do one thing, or shares state it should not.
2. TypesMake the wrong value fail to compile.The mistake was a wrong shape, id or unit passed along.
3. LintAdd or tighten a rule in the lint configuration.The mistake is a pattern a rule can name.
4. TestsAdd a test that fails on the mistake.The mistake is behaviour no type or rule sees.
5. DocsWrite it in the area's node, a glossary term, a decision record or a CLAUDE.md line.Only judgement or context was missing.

A lesson for another repo or team becomes a brief in writeups/briefs/, not a change here. A habit that crosses projects becomes a proposed global rule, written as text for the user to decide. A note in memory is never the fix.

Step 3: one proposal

One table, nothing built yet: the lesson, its evidence, the rung, the fix and the proof plan. List beside it every memory entry the fixes now cover, proposed for deletion. In an interactive session, ask once: build all, pick rows, or nothing. In a run past plan approval, ask nothing: build the rows that stay inside the run's approved scope (a test, a lint rule or a node for paths the run touched), and put every other row into the run's decision log as a parked row and into the closing summary.

Step 4: build and prove

For each approved row:

  1. Re-create the mistake in a scratch copy: git worktree add "$TMPDIR/retro-<n>" HEAD, then repeat the slip there. The new check must fail on it. Quote the failing line. When the mistake cannot be re-created, quote the earlier failing output instead and say so.
  2. Build the fix in the repo. The same check now passes on the fixed code. Quote the passing line.
  3. For the docs rung, the proof is that docs/knowledge/index.md maps the path to the node, and that the repo's knowledge lint passes when it has one.
  4. Keep evidence in writeups/scratch/<date>-retro/. Remove the scratch copy with git worktree remove --force "$TMPDIR/retro-<n>".

Then run the repo's gate once. Make one Conventional Commit per fix, never push, and delete the memory entries the user approved in Step 3.

Step 5: report

Per lesson: the rung, the files changed, the failing line and the passing line, or why it was skipped. Then the briefs written and the memory entries deleted.

If local.md exists next to this file, read it; where it disagrees with this file, it wins.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.