agentleFS
svy04svy04/ballast/skills/rehearsal/SKILL.md

rehearsal

Skill73 starsChanged 3 months agoMITView on GitHub

Test a deliverable on a zero-context reader before it ships. Use before shipping any document, guide, kit, or handoff meant to work without you, and before calling a deliverable done in goal Phase 5.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Execute, don't review: Follow the deliverable and actually do what it says — run the steps, fill the form, build the thing.

    line 17
  2. Distinctive:

    Report the stalls: Every place they stopped, guessed, or misread — line by line, no pushing past a gap.

    line 18
  3. Distinctive:

    A pass under the wrong persona is not a pass: If the rehearsal reader knew more — or less — than the real recipient, correct the persona …

    line 30

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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

Rehearsal — the recipient has no context

Whatever you just wrote reads clearly to you because you wrote it. The recipient has none of that. The failure mode this prevents: a deliverable that fails on first contact with its reader — after shipping, when every stall costs a round-trip.

The setup

Hand the deliverable — and nothing else — to a zero-context executor: a fresh subagent, or a person who hasn't seen this conversation. No history, no verbal explanation, no "what I meant was". If it needs an explanation to work, the explanation belongs inside the deliverable.

The instruction has three parts

  1. Persona, precisely. Who will actually receive this: what they know, what they don't, what tools they have, what language they read. Those facts come from the user or the deliverable's stated audience — if neither says who it's for, ask; the recipient is the user's fact to give, not yours to invent. A generic "reader" is the wrong test — the real recipient usually knows the domain and not your shorthand.
  2. Execute, don't review. Follow the deliverable and actually do what it says — run the steps, fill the form, build the thing. Reading and nodding finds nothing.
  3. Report the stalls. Every place they stopped, guessed, or misread — line by line, no pushing past a gap. The stalls are the finding, not a footnote.

Rounds

Fix what stalled, hand it to a fresh executor, repeat — three rounds at most. Round one tends to find the real blockers, round two finds what the fixes broke, round three is mostly false alarms: that's convergence.

Clean means the executor finished without a blocking stall — a report that points at text which already answers it is a false alarm, not a stall. Not clean by round three? The structure is wrong, not the wording: redesign instead of re-polishing, and a redesigned deliverable is a new deliverable — its rounds start again at one.

One redesign is normal. A second redesign that still isn't clean ends the loop: take the stall list to the user — the deliverable's shape is now their decision, not another rewrite.

Three rules

  • A pass under the wrong persona is not a pass. If the rehearsal reader knew more — or less — than the real recipient, correct the persona and rerun.
  • A clean pass earns the done-check, not the ship. Anything externally visible still leaves only with the user's click (goal's standing behavior).
  • Keep the log. Rounds, stalls, fixes — beside the deliverable, or in the goal file's done-check (memory/goal/<slug>.md) when the work runs under goal. The log is citable evidence that the deliverable survived contact (observed, dated); "it reads fine to me" cites nothing.

ballast's own READMEs went through this procedure before release (v0.5 converged in three rounds); the round logs live in the maintainer's workspace, not in this repository.


Part of ballast — foundations first, every solved path kept, done means checks pass.

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.