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 directory): the snapshot <slug>.md, the work's current truth, bounded; the log <slug>.log.md, everything that happened on the way, append-only; the contract CONTRACT.md, what binds the slices not yet built; and 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 own 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. The snapshot's size follows scope, which is what keeps it read closely rather than skimmed; the log's follows time, which costs nothing, because it is never read whole; the contract's follows slice count, which is why it cannot live in the file whose size must follow scope. 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, too: the pointer in the project's instruction file fires at session start, and a session summarised mid-slice is a new cold reader with the same name — what it remembers of the slice list is the summary's, and the file is the truth.
• Reading scope stays with the work at hand, however much the project has finished. 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 (the format names which commands). Every other slug's files stay closed, and the log stays unopened unless a specific question forces it in: a project with two finished works and one with two hundred cost a session the same. The full sweep is /genius with no argument, an occasional operation with its own scope.
• The contract changes by version, never by patch. Requirements moving mid-build is the normal case; the old contract was right for the world it was written in. 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" has no stopping condition and is satisfied by changing nothing. The invariant that makes it lossless — nothing leaves except into the log or CONTRACT.md, a link left behind — licenses the snapshot alone: the in-flight log is never compacted, summarised or tidied, because a kill-reason shortened to a verdict has been destroyed, not maintained. 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 — compact it back.
• 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 — all in one commit where .genius/ is committed, and at that 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.
• Absence is the record. A stage the user didn't type has no section and no log entry, and when work goes wrong later the missing section is the first suspect. No skip bookkeeping: not typing a stage is the decision.
• 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; Open holds only what is still owed an answer.
• Derived work gets its line the moment it's spotted. An edge worth testing, a refactor worth doing, a question worth its own work — left in whichever file the discovery happened in, it surfaces only when the user thinks to ask. One line in .genius/BACKLOG.md, in the shape the backlog format gives it, in any stage, and move on: a seed for a future /genius, not a plan. /genius lights these up every run; Tenacity sweeps a work's leftover Open items there; starting one removes its line, the new work file its home now.
• What binds is rewritten; what records is appended to. Writing at the moment of action is what makes a record honest and why some of it is wrong. 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, reasoning load-bearing, quotes verbatim, evidence as data, checked facts carrying their scope — is the record-prose skill's discipline, one place for every document under .genius/.
• Checkpoints are live, and parsable. Each is a real exchange with the user — a model answering its own interview confirms nothing, and one approving its own plan finds nothing. Where you are asking for a decision, lead with it and keep the sentences short; know what the ask actually is before demoting anything below it — at Wonder the story you offer for correction is the ask, at Discernment the consequences played back are. A dense report buys agreement rather than judgement, which is what checkpoints exist to collect.