agentleFS
shawnclyborshawnclybor/clybor-claude-tooling/.claude/skills/build-polish/SKILL.md

build-polish

Skill6 starsChanged 29 days agoMITView on GitHub

The final stage of a whole build, and the stage that owns done. Once the build's planned versions and increments are finished, build-polish runs the real thing rapidly until it matches its goldens, then marks the deliverable complete; build-evaluate is not run again. Phase 0 is a preflight gate: it writes the definition of done (the release standard, a named golden set with numeric floors, two independent witnesses, the end-user journey) and nothing runs until the owner confirms it. Then up to three rounds: one serialized run of the core function into a frozen snapshot; comparison against the goldens; parallel read-only subagents that check it and walk the user journey; an evidence-gated sequential-thinking checklist deciding whether each anomaly is really a problem; the smallest fix, under a KISS/YAGNI veto and code review. The end check stays small: real results, plus single mutation rows or sets whose output drives a fix. Triggers - polish the build, final polish, get it to done, is it done, /build polish.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If probes/run.sh exists, it was re-run this session with 0 MISMATCH.

    line 45

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Build Polish

Get to done. While a build is being built, each version or increment gets its own build-evaluate verdict — and none of those verdicts is the deliverable being done. The Yellow Sheet went through 1.0 to 1.4 that way, evaluated many times and never done. Polish is the end of the build: the owner defines done once, the real thing runs until it matches, and polish marks the deliverable complete.

Three measured facts shape it.

  • 45% of all must-fix findings across 21 review rounds sat in text the previous round's repair wrote (mem:gate_philosophy). Polish reviews by rule and by harness, not by panel.
  • Exit codes and counts have called builds done that were not — a green renderer over an empty tab, "workbook written" over 0 of 70 money cells, a floor 40 below its count. The done check reads the artifact, never the exit code.
  • Two drivers on one shared tree cost a whole measurement round on 2026-09-10 — the reason for the one-run cap below.

Where it sits

while the build is being built, per version or increment:
    prd → probe → validate → plan → estimate → execute → evaluate
at the end of the build, once:
    POLISH → the deliverable is done

Polish replaces any further evaluate. It never runs the full suite or the full mutation table: those did their job while the versions were built. It checks the finished thing against real examples, and uses single mutation rows, or small sets of them, where their output drives a fix.

Preconditions — REFUSE if unmet

  • The owner has called the build at its end: no planned version or increment is left to execute.
  • Polish runs on the last version's slug: .claude/PRPs/{slug}/prd.md and state.json exist, and the last increment's build-execute reported success.
  • If probes/run.sh exists, it was re-run this session with 0 MISMATCH.
  • The build names a core-function command and at least one golden with an oracle. With no golden there is nothing to polish against; that is build work — stop and say so.

Fixed caps

Three rounds. Stagnation — two rounds in which no ledger row left OPEN — runs five-whys, then stops. Three FAILs on one target stop the loop as a process defect (Hard Rule 9). No clock, ever (Hard Rule 8). One run of the core function at a time.

What the owner sees

WhenThe owner seesThe owner is asked
StartThe done definition, pre-filled from the release standard, the last PRD, state and every version's evaluateOnce: Confirm / Adjust / Stop
RoundsNothing. No status reports at round boundariesOnly for a target change, a scope call, or a fact only a human holds — after the repo was searched for it (Hard Rules 4 and 11)
EndThe deliverable marked complete, or stopped, and the report (§ Close)Only the questions the ledger could not settle

Where the rest lives (read before running the matching phase)

When you are about to...Read
Define DONE (Phase 0 preflight gate), load known state (Phase 1), or run a roundreferences/phases-0-1-round.md
Use the gated checklist (triage, done) or dispatch reviewersreferences/checklist-and-reviewers.md
Write the ledger or audit, use the Journey walker / Golden reader prompts, the worked example, or the Guidelinesreferences/ledger-prompts-example.md

Phase 0 is mandatory before any round. Do not start without reading references/phases-0-1-round.md.

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.