Every build, on the record.
A skill that keeps an audit trail of anything you build with an agent: what was done, why, what else was considered, who said yes. One record in Markdown for you and one in JSONL for the agent, written as you go.
Two weeks after a build, somebody asks why it was done that way. With a chat as your only record, the answer is gone. This skill writes the record while you work: when a real decision is made it captures the reasoning and the alternatives, when you approve something it logs that gate, and at a checkpoint it compiles the lot into a Build Record. It is written to a real standard, the one auditors use, so a person with no prior connection could read it and understand exactly what happened and why. You do not have to care about auditors for that to be useful.
/build-ledger with six commands: start, decision, gate, checkpoint, eval, compile. Templates for a build record, a decision record and a traceability matrix. Two agents, a recorder and an auditor. The quality checklist.
Zero tribal knowledge: anyone can pick up where a session left off. Every deliverable maps back to the original ask. Decisions carry their reasoning, not just the outcome.
You say start at the top of a real build. The skill picks a depth by itself, from a lightweight summary to a full record with a traceability matrix, and you can force one. At checkpoints it compiles; at the end it runs a fresh-eyes eval on its own record.
Say start. Answer when it asks what you decided and why. Read the record at the end and fix what is wrong, because you are the only one who knows.
When to switch it on, and when not to.
Use it for any build that is more than trivial: more than about fifty lines or more than one file, anything for a client, any architecture decision, anything someone might later ask "why" about. Do not use it for a quick question, a typo fix, or a research session with no deliverable; the skill's own first tier, ephemeral, is "skip the record".
The skill's newer version hands decisions to a second skill, /log-decision, so one-shot decisions and build-time decisions land in the same place. That pairing is worth having; it is also a second install. The one The Lab hands you is the version that works on its own.
What happens in a session?
Three things, in order, and six commands that drive them.
- Capture, as you work. Every real decision gets an entry: what was being decided, what was chosen and why, what else was considered and why it lost, who decided, how confident. Every human yes, no or redirect is a gate entry.
- Compile, at checkpoints. The entries become a Build Record: a summary, the timeline, the decision log, and for the deeper tiers a matrix that maps each deliverable back to the ask.
- Certify, at the end. A fresh-eyes eval reads the record as a stranger would and says what is missing.
/build-ledger start /build-ledger decision /build-ledger gate /build-ledger checkpoint /build-ledger eval /build-ledger compile
Depth is picked for you from the work: ephemeral (skip), operational (a light record), decision-grade (decisions and alternatives), audit-grade (plus the traceability matrix), regulatory (plus retention controls). Force one with /build-ledger start --tier audit.
The skill can capture on its own through hooks and a session-end step, and it names other tools it plugs into. Those come from the workbench it was written in. On a fresh install, drive it with the six commands by hand; that is the whole skill, and it works.
What you can ask your agent, once it is on
Six asks, in the order a build goes. Copy, paste, read what comes back.
/build-ledger start. The build is: [one sentence]. Pick the depth tier and tell me why.
/build-ledger decision. We chose [X] over [Y] because [reason]. Record the alternative and why it lost.
/build-ledger gate. I approved [the thing]. Record it as a human approval with the time.
/build-ledger checkpoint. Compile what we have so far and show me the decision log.
/build-ledger eval. Then tell me the three questions an auditor with no context would still have.
/build-ledger compile. Finalise the record and tell me where both files are.
Words you now own
- Build Record. The compiled document for one build: summary, timeline, decisions, and for the deeper tiers the traceability matrix. Markdown for you, JSONL for the agent.
- Decision record. One entry: what was decided, what was chosen and why, what lost and why, who decided, how sure.
- Gate. A moment a person said yes, no, or "not like that". Logged with the time, so approvals are never a memory.
- Traceability matrix. A table that maps every deliverable back to the line in the ask that wanted it. The audit-grade tier adds it.
- Depth tier. How much record the work deserves, picked from the work itself. Five tiers, from skip to regulatory.
- Fresh-eyes eval. The skill reading its own record as a stranger and listing what a stranger could not follow.
Before you rely on it
Three habits, because a record is only as good as what went into it.
- It cannot record a decision you made in your head. If you decided something silently, say it out loud to the agent, or it is not in the ledger.
- Read the record. The eval catches gaps in structure. Only you catch a reason that is wrong.
- Keep secrets and names out of a record you might share. A Build Record travels. Client names, keys and anything private belong in the work, not in the trail.
The record is meant to be readable by someone with no connection to the work. Write it so that would be fine.
Fair questions
No. The regulatory tier is for real SOX or HIPAA exposure; the operational and decision-grade tiers are for any build you might have to explain later, which is most of them.
A skill is a folder with a SKILL.md, and both apps read that format. In Codex you call it with a dollar sign instead of a slash.
Into your workbench, beside the build. Ask the skill where it wrote them when it compiles; it tells you both file paths.