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), 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](FILE-FORMAT.md), the one home for those rules; the backlog's shape is [BACKLOG-FORMAT.md](BACKLOG-FORMAT.md), and the measurements behind the rules are [FORMAT-EDGES.md](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](FILE-FORMAT.md), Open); starting a seed removes its line only once the work has taken the seed's content up ([BACKLOG-FORMAT.md](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.

A done work's folder stays in place, the snapshot compacted at close-out to what history needs, its post-mortem line indexed into `.genius/HISTORY.md` (the `tenacity` skill writes it). Abandoning honestly (`stage: done`, post-mortem `abandoned — <reason>`) beats a zombie file.