Comprehension split: the shared corpus keeps the facts, the planning folder keeps the working

[m2ux]

Summary

When a work package studies unfamiliar code, it writes down what it learned into a shared library of reference documents that outlives the session. That library was collecting two different kinds of writing at once: settled statements about how the code works, and the working that produced them — the questions the pass opened, the investigations that closed them, the alternatives it weighed and the items it decided not to chase. Someone opening the library months later to understand a subsystem had to read around another session's notebook to find the facts.

This change sends each kind where it belongs. The shared library keeps what is true about the code. The questions and investigations stay with the work package that raised them.

What happens today

The comprehension activity writes four times, and every write goes to the same shared directory. The step that records a deep dive declares its output as a file in that directory; so does the step that records the initial survey. There is no second destination anywhere in the definition, so the split this change makes was not expressible.

The consequences show up in the library. One artifact in the reference corpus that prompted this work had grown to 371 lines, of which roughly 150 were a table of numbered questions and the dated investigation write-ups that answered them — material meaningful only to the review that produced it. Others in the same corpus have reached 173 KB and 110 KB, three to four times the size at which reading the artifact is still cheaper than reading the code. The instruction to preserve prior content and the instruction to keep an artifact near 150 lines were pulling against each other, and preservation was winning.

The document's shape had drifted too. Two of its sections — one for the project's architecture, one for its key abstractions — were an arbitrary cut through the same structural material, while the runtime material was appended later as a third section that reads as a bolt-on. Design rationale was recorded as a hypothesis to be validated, so the reference corpus carried hedged guesses rather than statements.

The fix

Two templates instead of one. The guide now defines a corpus artifact and a comprehension log separately. The corpus artifact splits at the top level into structure — what exists and how it is arranged — and behaviour — what happens once the code runs. That cut dissolves the two overlapping structural sections and gives the runtime material a home rather than an appendix. Rationale is titled as inferred, so the whole section carries the epistemic warning once and its entries can then state the design plainly.

A rule for what crosses. A promotion section decides what moves from the log into the corpus: the settled outcome crosses, the derivation stays. When a question resolves, its answer is written into the corpus section that owns it as a statement about the code, and the reasoning that reached it stays with the work package. Facts persist across passes; wording is free to be merged or restated when a new fact supersedes the old phrasing.

A second place to write. The activity now writes twice per deep dive — once to the shared corpus, once to the planning folder. No new machinery was needed: the write operation already defaults to the planning folder when no directory is named. The log write also moved to after the step that revises open questions, so the revised questions are the ones that get saved; previously the only write ran before that step.

House style for both. Eight fill rules now govern how either document is written. Every section opens with a paragraph saying what the reader is looking at. Prose names things in words and links to their definitions, leaving code identifiers to tables, diagrams and link targets. Lists are introduced with a demonstrative rather than a count, since a count goes stale the moment an entry is added, and where a value matters the rule is to name the constant rather than the number it currently holds. A section covering more than one topic subdivides. A section whose subject is a shape carries a diagram of it.

Why now is cheap

The receiving side already worked. The write operation's directory argument has always been optional with the planning folder as its default, so the second destination cost one step with one argument rather than a new capability. The mechanical checks that guard these definitions — schema validity, reference resolution, binding fidelity, the requirement that every persisted filename map to a creation guide — all pass without changes to any of them.

Scope of change

Ten files. The guide gains two templates, a promotion section and the fill rules. The comprehension technique group gains a second declared output and drops the layout instructions it had been restating in its own procedure. The question-revision technique retargets to the log. The activity gains two write steps and reorders one. Two techniques outside the group were pulled in because they reference contracts that changed, along with the resource index that maps filenames to their guides.

Acceptance criteria

• A deep dive produces both artifacts, and the reference corpus contains no numbered question table, no dated investigation sections and no follow-up register.
• Every fact a resolved question produced appears in the corpus section that owns it, stated as a property of the code.
• The full guard suite passes — 26 checks, no failures, none unmeasured.
• Both templates are reachable by anchor, so a technique needing one is delivered only that section.

Non-goals

Around sixty artifacts already in the reference corpus keep their current shape. This change governs what gets written from here on; converting the back catalogue is separate work, and several of those artifacts would need splitting into more than one area to fit the line budget at all.

Review notes

A canon audit ran over the change surface — the ten changed files plus three that reference contracts they changed and two in another workflow that borrows the activity, against a target surface of 168 definition files. It raised seven findings, all fixed in this branch: one duplicated invariant with two homes, one piece of operative framing sitting where no section anchor could deliver it, two overlapping fill rules with no stated precedence, a procedural duty on a bind contract, one stale claim in a README that survived the behaviour change, and two declared inputs no procedure step referenced.

🤖 Generated with Claude Code