genius-file

The Work File

One piece of work = one folder at .genius/<slug>/ (a ## Working Genius section in CLAUDE.md/AGENTS.md may pin a different parent), holding:

• the snapshot <slug>.md, the work's current truth, bounded
• the log, everything that happened on the way, append-only, as a tree: the root <slug>.log.md naming one branch per stage, slice or contract version under log/
• the contract CONTRACT.md, what binds the slices not yet built
• the work's own artifacts

The shape of all of it — templates, the compaction question, the ceiling and its instrument, the invariant, the link rules — is FILE-FORMAT.md, the one home for those rules; the backlog's shape is BACKLOG-FORMAT.md, and the measurements behind the rules are FORMAT-EDGES.md.

The concept: the files, not conversation memory, carry the work — and what a work knows grows by three different laws, so it gets three files with three different rules. Conflate any two and the file grows with every discovery until nobody reads it closely, which is how a record dies while still being written to.

What that takes:

• Read the snapshot before acting; write the moment a decision lands. It outranks whatever you remember about the work. Re-read it after your own context is compacted: a session summarised mid-slice is a new cold reader, and the file is the truth.
• Reading scope stays with the work at hand. Starting or resuming costs three reads: list .genius/ for the slug, read that snapshot, read .genius/DECIDED.md if settled ground might be at stake. CONTRACT.md is a fourth, earned when you are about to build, attack or verify against it. Every other slug's files stay closed, and the log stays unopened unless a specific question forces it in, and then only the one branch that question names. An anchor to link is never such a question: python3 ${CLAUDE_SKILL_DIR}/measure.py anchors <slug> lists every branch, every ## key and what already links it, because a file opened whole stays in the context to the end of the work. Appending to the log opens nothing: python3 ${CLAUDE_SKILL_DIR}/measure.py append <slug> <branch> <key> [<about>], the entry on stdin, writes the ## <key> heading, creates a new branch with its root line, continues a -wip entry, and refuses a key that already exists — the mechanics the format asks of every append, done by the one thing that cannot misremember them. A project with two finished works and one with two hundred cost a session the same.
• The contract changes by version, never by patch. Requirements moving mid-build is the normal case. A change of shape — criteria, scope, slices, seams — is the new version whole in CONTRACT.md, the old whole in the log with what overturned it, one changelog line in the snapshot; a single value that measured differently is the errata skill's line-level supersede, no bump. So a change costs the same at churn one and churn ten.
• Compaction is part of closing, and it has an object. Every slice close, contract bump and stage close puts the format's one question to each snapshot line — does this line still constrain work that isn't finished? — and routes the answer; without the question, "compact to current truth" is satisfied by changing nothing. The invariant — nothing leaves except into the log or CONTRACT.md, a link left behind — licenses the snapshot alone: the in-flight log is never compacted or tidied, because a kill-reason shortened to a verdict has been destroyed. Tenacity distills a done work's log once, by one announced rule; /distill catches up older done work; /compact catches up a snapshot that drifted.
• The snapshot is the only path anyone has to know. Every section links the log entries that back it. A cold session that must trawl the log to act is the sign that state leaked into history.
• A slice's evidence rides the commit that closes it: the code, the log entry naming per criterion what ran and what it showed, the snapshot compacted, and CONTRACT.md where the slice left something binding — one commit where .genius/ is committed, the same moment where it is gitignored. The evidence goes in the log, not the commit message: a message can't be corrected, linked, read in the diff, or survive a squash. A close is one write per file, composed before it is written, because every tool call re-reads the whole context.
• Absence is the record. A stage the user didn't type has no section and no log entry; not typing a stage is the decision, and when work goes wrong later the missing section is the first suspect.
• Assumptions are visible. A decision made without the user is an assumed: <question> → <answer> line in Open, surfaced at next contact — an honest assumption beats a hollow confirmation. Consumed, it moves to the log with what consumed it.
• Derived work gets its line the moment it's spotted. An edge worth testing, a refactor worth doing, a question worth its own work: one line in .genius/BACKLOG.md, in the backlog format's shape, in any stage — a seed, not a plan. /genius lights these up. An Open item that is work reaches the backlog only through its own work's log, Tenacity's sweep included (FILE-FORMAT.md, Open); starting a seed removes its line only once the work has taken the seed's content up (BACKLOG-FORMAT.md), because a seed is lossy and one was measured reaching no section of its work.
• What binds is rewritten; what records is appended to. The snapshot, the index line, the glossary term get rewritten in place; the log gets appended to and otherwise left alone, because its worth is that it is what was written then. The errata skill holds the discipline; /reconcile sweeps the drift no session tripped over.
• How the sentences are written — for a cold reader and the owner both — is the record-prose skill's discipline, one place for every document under .genius/.
• Checkpoints are live, and easy for the user to read. Each is a real exchange with the user — a model answering its own interview confirms nothing. Where you are asking for a decision, lead with it and keep the sentences short — at Wonder the story you offer for correction is the ask, at Discernment the consequences played back are — because a dense report buys agreement rather than judgement.