Genius File

---
name: genius-file
description: Read and update Working Genius work files — the work's folder holding the bounded snapshot a cold session acts on, the append-only log behind it, and the contract that binds the unbuilt slices. Use when a stage skill needs the work-file discipline, when the user asks what work is in flight or where a piece of work left off, or before resuming any work tracked under .genius/.
---

# 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), holding the **snapshot** at `<slug>.md` — the work's current truth, bounded — the **log** at `<slug>.log.md` — everything that happened on the way, append-only, created at its first entry — the **contract** at `CONTRACT.md`, and this work's own artifacts. The shape of all three lives in [FILE-FORMAT.md](FILE-FORMAT.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 holds what a cold session acts on: the confirmed problem, the decision, which contract version binds, the slices and where they stand, what is still open. Its size follows scope, never time — that is what keeps it read closely rather than skimmed. The log holds how it all came to be: the interview, the battlefield, superseded contract versions, slice evidence, corrections. Its size follows time, which costs nothing, because it is never read whole — a link is followed into it when someone asks "why". The contract holds what binds the slices not yet built — the seams, the pinned values, the conventions the build introduced — and its size 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. `stage:` names where the work is; `contract:` names the version that binds.
- **Reading scope stays with the work at hand, however many pieces of work the project has finished.** Starting or resuming a piece of work costs three reads: list `.genius/` to find the slug (or confirm none exists yet), read that slug's snapshot, and read `.genius/DECIDED.md` if the work might touch settled ground. Nothing beyond those three for a status view, a resumption, or a new `/wonder`. A fourth read is earned, never assumed: `CONTRACT.md` opens when you are about to build, attack, or verify against what binds, and the snapshot's pointer serves everyone else ([FILE-FORMAT.md](FILE-FORMAT.md) names which commands that is, and on what condition — one place, since a roster kept in two drifts the moment a command is added). Every other slug's files — in flight or done — stay closed; the log stays unopened too, unless a specific question forces it in. What the rule protects is that the cost does not grow with the project's history: a project with two finished pieces of work and one with two hundred cost this session the same. The full-project sweep (`/genius` with no argument) is a different, occasional operation with its own scope — not what an ordinary session start pays for.
- **The contract changes by version, never by patch.** Requirements moving mid-build is the normal case, not a failure — the old contract was right for the world it was written in. So a change costs the same at churn one and churn ten: the new version written whole into `CONTRACT.md`, the old version moved whole into the log with what overturned it, one changelog line left in the snapshot pointing at it. What earns a bump is a change of *shape* — criteria, scope, slices, seams. A single value that measured differently is the `errata` skill's line-level supersede: binding line rewritten in place, log entry appended, no bump.
- **Compaction is part of closing, not a cleanup someone must remember — and it has an object, not just a moment.** Every slice close, contract bump, and stage close rewrites the snapshot to current truth, and the rewrite is one question asked of each line: **does this line still constrain work that isn't finished?** [FILE-FORMAT.md](FILE-FORMAT.md) holds the three destinations the answers route to, the two tie-breaks, and what the question is answered against — one place, so the branches cannot drift apart from each other. "Compact to current truth" without that question has no stopping condition, and a rewrite with no stopping condition is satisfied by changing nothing. The invariant that makes rewriting lossless — nothing leaves the snapshot except into the log or into `CONTRACT.md`, always with a link left behind — is a license the snapshot alone holds while work is in flight: the in-flight log is never compacted, summarized, or tidied, because those losses are silent and permanent — a kill-reason shortened to a verdict has been destroyed, not maintained. A *done* work's log is the one exception: Tenacity's close-out distills it, once, by one announced rule — what the repo now answers leaves, what it cannot stays (the `tenacity` skill holds the move; `/distill` runs it retroactively on done work that closed without it). Where a snapshot drifted instead — a close that never put the question to it — `/compact` runs this move retroactively, the same way.
- **The snapshot is the only path anyone has to know.** Every section links the log entries that back it, so nothing is found by convention or by guessing. And the log is never read whole: a cold session that must trawl it to act is the sign that state has leaked into history — compact it back.
- **A slice's evidence rides the commit that closes it.** A slice closes in one commit: the code, the log entry naming per criterion what ran and what it showed — written while the output is still on screen — and the snapshot compacted, all where `.genius/` is committed, and at that same moment where it is gitignored. The evidence goes in the log and not the commit message, for the reasons a record exists at all: a message can't be corrected when a later slice finds the claim wrong, can't be linked to, isn't in the diff a reviewer reads, and doesn't survive a squash or a rebase.
- **How the sentences themselves are written — for a cold reader and for the owner, reasoning kept 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/`.
- **Absence is the record.** Every stage is a command the user types; one they didn't type simply has no section and no log entry — the snapshot shows what ran and what didn't, 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 the snapshot's Open section, 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.** Building one thing surfaces others — an edge worth testing, a refactor worth doing, a question worth its own piece of work. Left in whichever file the discovery happened in, they surface only when the user thinks to ask, which is the flow losing ideas it already had. The moment one appears, in any stage, append one line to `.genius/BACKLOG.md` — what it is, why it's worth doing, where it came from (`<slug>` + log anchor) — and move on: the line is a seed for a future `/genius`, not a plan, and it costs one line for the discovery to survive the session that made it. `/genius` lights these up every time it runs; Tenacity's close-out sweeps a work's leftover Open items there (or resolves them), so nothing worth doing rides a done file into the dark. Starting a backlog item removes its line — the new work file is its home now. The line's shape: `- **<what>** — <why it matters>. From [<slug>](<slug>/<slug>.log.md#<anchor>), <date>.` One physical line, 300 characters at most — the `record-prose` skill holds why. — `BACKLOG.md` sits at `.genius/`, so its links are relative to that, one folder above the work's own, and carry the named work's path as that work actually sits: the folder form above, or a bare `<slug>.log.md` where it is still flat ([FILE-FORMAT.md](FILE-FORMAT.md) holds the rule, since the same basis question reaches `DECIDED.md` and `HISTORY.md`).
- **The log is corrected, never rewritten.** Writing at the moment of action is what makes a record honest, and it is also why some of what gets written is wrong. What binds — the snapshot, the index line, the glossary term — gets rewritten in place; what records gets appended to and otherwise left alone, because its worth is that it is what was written then. Both carry the evidence that overturned the line, and a corrected fact goes back in carrying the scope it should have had. The `errata` skill holds the discipline; `/reconcile` sweeps the drift no session happened to trip over.
- **Checkpoints are live.** Each checkpoint is a real exchange with the user, the Wonder interview above all — a model answering its own interview confirms nothing, and a model approving its own plan finds nothing.
- **A checkpoint the user can't parse is a worse checkpoint.** Where you are asking for a decision, lead with it and keep the sentences short, so someone who has already made up their mind can skip the rest. Know what the ask actually is before demoting anything below it: at Wonder the story you offer for correction *is* the ask, and at Discernment the consequences played back *are* the ask — neither is background a reader may skip. A dense report buys agreement rather than judgement, which is the thing checkpoints exist to collect.

A done work's folder stays in place — snapshot, log, contract and artifacts, the snapshot compacted at close-out to what history needs: they're decision history, and their post-mortem line is indexed into `.genius/HISTORY.md` (the `tenacity` skill writes it) so it calibrates the next run without reopening the folder. Abandoning honestly (`stage: done`, post-mortem `abandoned — <reason>`) beats a zombie file.