The room of requirement

🦋 The Room of Requirement

"Your repo asked for instructions it never had. Here they are."

Every other pass in this book grades instructions that exist. A repo with no memory file gets nothing from them — a full sheet of honest verdicts of no subject, truthful and useless. That repo is the one most likely to benefit from anything at all, and it is the one the book had no answer for.

This is the only pass that writes rather than grades. It still proposes: the file is a fix-table row like any other, and nothing lands until the user approves it.

What to scan

Inputs, in order of authority. Later sources never override earlier ones — they fill gaps.

1. The repo's own machinery. Package manifests and lockfiles (which package manager is real, not which is fashionable), script targets, CI workflow steps, linter and formatter config, test runner config, the directory layout, and whatever .gitignore and generated-file markers say is not hand-written.
2. README and CONTRIBUTING. Conventions the project already states in prose. Extract, do not restate: if the README says it well and the model reads the README, the memory file needs the rule only when a session would act wrongly without it.
3. Correction history, if it exists. the-remembrall's clusters are the strongest possible input here — a rule the human has already had to give three times, with its wording settled. Skip this input silently when there are no transcripts; do not block on it.

Derive, never invent. Every proposed line cites what it came from — a script name, a workflow step, a config key, a transcript correction. A line you cannot cite is a guess about someone else's project, and it will be obeyed exactly as hard as the true ones.

What goes in

Four things, and the file is mostly done:

• The commands. Build, test, lint, typecheck, run — exact and copy-pasteable, with the right package manager. This is the single highest-value content and the one thing the model cannot infer reliably: it self-verifies its reasoning, not your toolchain.
• The two or three conventions a new contributor gets wrong. Not the style guide — the surprises. Which directory is generated, which file is the source of truth for a value that appears in three places, the import path that looks right and isn't.
• What is generated or vendored. Anything hand-edits get overwritten in, anything a tool owns. Cheap to state, expensive to discover by losing work.
• Anything destructive that must be confirmed first. Migrations, deploys, history rewrites, anything that reaches a shared system.

What never goes in

These are the anti-patterns — authored fresh, they arrive pre-broken, and the rest of the book would flag them on its next pass:

1. Aspirational values. "We value simplicity", "write clean code" — no trigger, no scope, not falsifiable. clarificus-maxima class 3 and 4, shipped on day one.
2. What a linter already enforces. If the formatter fixes it, prose about it is unread text that competes with rules that matter. Mechanism beats prose; the mechanism is already there.
3. Restatements of the README. Duplication drifts, and the drifted copy wins in novel situations because it matches more contexts.
4. Anything the model infers from the code. Language, framework, obvious layout. Text confirming what is already visible costs attention and buys nothing.
5. Emphasis. No CRITICAL, no YOU MUST, no caps. A file authored today has no scar tissue to justify shouting, and the 5-family over-obeys it — quietus-capslockius on a file this book wrote would be an embarrassment.
6. Verification prose. "Double-check your work" is redundant on this model family. A rule naming a concrete command is not verification prose and belongs in — that is the commands section above.

Size

Target tens of lines. Treat a hundred as a signal you are inventing. Most of this book's effort goes into shrinking files that grew for years; authoring a large one would be a strange way to start. If the repo genuinely needs more than that, the excess is usually per-directory content — propose a nested file where it applies, not more root.

Which file

Follow whatever the repo already leans toward: CLAUDE.md for a Claude-only project, AGENTS.md when the repo is multi-tool or already carries other agent config. If neither exists and there is no signal, offer both names and let the user pick — the content is identical either way.

Bounds

• Scope: authoring one memory file for this repo. Not skills, not agents, not hooks, not CI. Not a second file unless the first proved genuinely too small.
• Cap: one proposal, tens of lines. If a section is running long, that content probably belongs in a nested file or does not belong at all.
• Done when a proposal exists and every line in it cites its source. Not when the file feels complete — a starter file is meant to be added to by the people who hit the gaps.
• This pass is N/A when a memory file already exists. Its triage row is the inverse of every other pass in the book: it runs only on a repo the rest have nothing to say about. Improving an existing file is the rest of the book's job.
• Read-only until approved, like every other pass: propose, then write only what the user accepts.
• See skills/opus-pocus/references/casting-safety.md for the full rules.

Report format

The proposed file in full, then a source table: every line or section against the input it was derived from (package.json:scripts.test, .github/workflows/ci.yml:19, a transcript correction with its date). Then what you deliberately left out and why — the reader needs to see the restraint to trust the inclusions.

SCANNED NOTHING if the repo has no manifests, no CI, no README, and no transcripts — there is nothing to derive from, and inventing a file from an empty repo is exactly the guess this pass refuses to make.