donald-ada/workinggenius / skills/genius-file
genius-file
VerifiedRead 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.mdnaming one branch per stage, slice or contract version underlog/ - 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.mdif settled ground might be at stake.CONTRACT.mdis 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, 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, what overturned the old in the log with the commit that holds its text, one changelog line in the snapshot; a single value that measured differently is theerrataskill'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. The log stays short by what goes into it — what the repo and its commits cannot answer (FILE-FORMAT.md, The log) — never by a pass that cuts it later;/compactcatches 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.mdwhere 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./geniuslights 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
errataskill holds the discipline;/reconcilesweeps the drift no session tripped over. - How the sentences are written — for a cold reader and the owner both — is the
record-proseskill'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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |