From 5a1d18b97e781af030b843a6ef17a20ab2ea6bf9 Mon Sep 17 00:00:00 2001 From: dubedad Date: Mon, 27 Jul 2026 10:32:45 -0400 Subject: [PATCH] Let stage numbering express independence, and add the join contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Folder numbering is a total order, so a pipeline can only say "after." Independent steps therefore have to be numbered as though each depends on the last, which asserts a dependency that does not exist. In a method whose structure is its documentation, that is a defect rather than a style choice. Siblings that share a number and differ by a letter (02a_, 02b_) are unordered with respect to each other; the next integer runs after all of them. The stage after a fan is a join, and its contract does the waiting by naming every sibling output as an exact working input. The existing Inputs section already carries this, so no new mechanism is introduced. Two limits are stated with the convention: fan width is bounded by human attention rather than compute (two to four branches; wider and uniform means the unit is a record, so use a record library), and a fan is declared at design time, never inferred mid-run — a run that decides its own width has to glob its inputs and stops being readable before it executes. Also reconciles a notation clash this introduces: "Where ICM loses" used "3a vs 3b" for mutually exclusive alternatives, which would now read as concurrent peers. Reworded, and the distinction made explicit — a fan runs every branch at a fixed width, so nothing is decided at run time, and it does not fall under the mid-pipeline branching guardrail. Co-Authored-By: Claude Opus 5 --- SKILL.md | 8 +++++--- assets/templates/join-CONTEXT.md | 30 ++++++++++++++++++++++++++++++ references/core.md | 27 +++++++++++++++++++++++++-- references/forms.md | 1 + 4 files changed, 61 insertions(+), 5 deletions(-) create mode 100644 assets/templates/join-CONTEXT.md diff --git a/SKILL.md b/SKILL.md index 9e00a06..28a2d28 100644 --- a/SKILL.md +++ b/SKILL.md @@ -17,7 +17,7 @@ Every ICM, whatever its form, obeys these. When building or restructuring, enfor 1. **One folder, one job.** Each folder does a single step or holds a single kind of thing, and states its own purpose in a file inside itself. The structure is the documentation. 2. **A small, stable entry file.** `CLAUDE.md` (or `AGENTS.md`) at the root answers "where am I, where does everything live, where do I go for task X" — and nothing else. Target under ~60 lines. It routes; it never holds content. -3. **Numbering encodes order.** `01_`, `02_`, … where sequence matters. Renaming folders reorders the pipeline — that is the point. +3. **Numbering encodes order.** `01_`, `02_`, … where sequence matters. Renaming folders reorders the pipeline — that is the point. Where sequence does *not* matter, say so: siblings sharing a number and differing by letter (`02a_`, `02b_`) are unordered with respect to each other, and the next integer runs after all of them. Never assert an order that isn't real. 4. **Every folder-level contract is explicit.** A `CONTEXT.md` per working folder: what it reads (inputs), what it does (process), what it writes (outputs), what a human checks. See [assets/templates/stage-CONTEXT.md](assets/templates/stage-CONTEXT.md). 5. **Factory vs. product.** Reference material (rules, voice, schemas, templates — stable across runs) lives structurally apart from working artifacts (outputs, drafts — new every run). Configure the factory once; the product is what each run emits. 6. **Every output is an edit surface.** Intermediate outputs are plain files a human can open, edit, and save before the next step reads them. Nothing moves forward until a person has read the last output. @@ -37,11 +37,12 @@ Every ICM, whatever its form, obeys these. When building or restructuring, enfor - What is the repeating unit of work? (an episode, a client, a report, a person, a team?) - Walk me through one run, start to finish. Where do you stop and check something before continuing? +- For each step: does it need the step before it, or just the original input? Steps that only need the original input are independent. - What stays the same every run (voice, rules, brand, schema) vs. what is new every run? - What does "done" look like — what artifact leaves the workspace? - Who else touches this, and what do they need to find without asking you? -Their pauses become stage boundaries. Their "I always check X before Y" become human gates. Their "it always has to sound like / follow Z" becomes factory reference material. +Their pauses become stage boundaries. Their "I always check X before Y" become human gates. Their "it always has to sound like / follow Z" becomes factory reference material. Their "those two don't depend on each other" becomes a shared number, not a sequence. **2. Pick the form.** Read [references/forms.md](references/forms.md) and choose: @@ -89,6 +90,7 @@ Validate any ICM — new or restructured — by walking it cold, as an agent wit - Can you state pipeline status purely by scanning what exists in `output/` folders (or node frontmatter)? - Is any routing file carrying content payload? Move the payload to a shelf; leave a pointer. - Is any fact stored in two places? Pick one home; link from the other. +- Does any stage share a number with a sibling? Then confirm neither reads the other's output, and that the next stage names all of them in its inputs. A lettered stage reading a lettered sibling means the numbering is lying — renumber serially. - Token check: entry file + one contract + its inputs should land in roughly 2k–8k tokens. If a step fails, fix the structure — not by explaining more, but by moving or splitting files until the walk works. @@ -103,4 +105,4 @@ If a step fails, fix the structure — not by explaining more, but by moving or - [references/core.md](references/core.md) — the five design principles, the five-layer context hierarchy, naming conventions, token discipline. Read when writing contracts or when a structural call is contested. - [references/forms.md](references/forms.md) — the five forms in depth: skeleton trees, defining moves, failure modes. Read at step 2 of Build mode or step 2 of Restructure mode. -- [assets/templates/](assets/templates/) — copyable starters: `CLAUDE.md`, workspace `CONTEXT.md`, `stage-CONTEXT.md`, `node.md`, `schema.md`, `questionnaire.md`. +- [assets/templates/](assets/templates/) — copyable starters: `CLAUDE.md`, workspace `CONTEXT.md`, `stage-CONTEXT.md`, `join-CONTEXT.md`, `node.md`, `schema.md`, `questionnaire.md`. diff --git a/assets/templates/join-CONTEXT.md b/assets/templates/join-CONTEXT.md new file mode 100644 index 0000000..0e205db --- /dev/null +++ b/assets/templates/join-CONTEXT.md @@ -0,0 +1,30 @@ +# {NN}_{stage-name} — {the job in five words} + +One job: {reconcile the parallel branches into a single {artifact}}. + +## Waits for +{NN-1}a, {NN-1}b, {NN-1}c — every one of those `output/` folders must be +non-empty. If any is empty, stop and name which one; do not proceed on +partial input. + +## Inputs +- Working (this run): ../{NN-1}a_{branch}/output/{file} +- Working (this run): ../{NN-1}b_{branch}/output/{file} +- Working (this run): ../{NN-1}c_{branch}/output/{file} +- Reference (every run): ../../_shared/{rules-file}.md + +Do NOT load: {the branches' own reference folders — their constraints were +applied upstream and restating them here re-does work already done}. + +## Process +1. Read every branch output. +2. {Merge, following the reference constraints.} +3. Where branches contradict each other, flag the contradiction inline + rather than choosing — the choice belongs to the human check. + +## Outputs +- {artifact}.md → output/ + +## Human check +Read the flagged contradictions first — each is a decision you own, not the +model's. Resolve them in place. Nothing downstream runs while a flag is open. diff --git a/references/core.md b/references/core.md index 1cd426d..8621f3d 100644 --- a/references/core.md +++ b/references/core.md @@ -2,7 +2,7 @@ The canon, distilled from the ICM paper (arXiv:2603.16021) and production workspaces. Read this when writing contracts, arguing a structural call, or checking a workspace against the method. -Contents: Five principles · Five-layer hierarchy · Stage contract format · Naming conventions · Library rules · Token discipline · Where ICM loses +Contents: Five principles · Five-layer hierarchy · Stage contract format · Parallel stages and the join · Naming conventions · Library rules · Token discipline · Where ICM loses ## The five design principles @@ -59,9 +59,32 @@ Read the draft aloud. Verify the argument order survived from research. Edit in Rules: inputs are exact paths, split working vs reference. The process is numbered and short — constraints live in L3 files, not restated here. Exactly one human check, stated as something a person does, not a vague "review." +## Parallel stages and the join + +Folder numbering is a total order, so a plain `01/02/03` line can only say "after." When steps are genuinely independent — three scans that all read the same brief, none of which reads another's output — numbering them in sequence asserts a dependency that does not exist, and an agent walking the workspace cold will believe it. The structure is the documentation; a structure that lies is a defect, not a style choice. Give independent steps one number and different letters: + +``` +stages/ +├─ 01_scope/ → output/brief.md +├─ 02a_market/ reads 01 +├─ 02b_competitors/ reads 01 +├─ 02c_regulatory/ reads 01 +└─ 03_synthesis/ reads 02a + 02b + 02c +``` + +Status still comes from scanning `output/`; it simply reads as a checklist rather than a cursor. `02a ✓ 02b ✓ 02c ▢` says one branch is outstanding and the synthesis is blocked — more informative than a single position on a line. + +The stage after a fan is a **join**, and its contract does the waiting (copy from `assets/templates/join-CONTEXT.md`). It names every sibling output as an exact working input and states what it is waiting for. No new mechanism is needed — the Inputs section already carries this. When branches contradict each other, the join surfaces the conflict as an editable file instead of quietly picking a winner; that contradiction is a finding, and putting it in front of a person before the expensive downstream work is the same move as any other stage boundary. + +Two limits, both real: + +- **Fan width is bounded by human attention, not by compute.** The bottleneck in an ICM is the human gate, not model wall-clock — parallelising three stages that each need twenty minutes of review saves seconds and creates a review pile. Two to four branches. If the work is wider and uniform (score twelve processes, audit thirty files), the repeating unit is a record, not a stage: use a record library and let the index log be the join. +- **A fan is declared, never inferred at run time.** Independence is a fact about the work, settled when the workspace is designed. A run that decides its own width cannot name its inputs — it has to glob them — and the structure stops being readable before it executes. See *Where ICM loses*. + ## Naming conventions - Stage folders: `NN_kebab-name` (`01_research`). Ordinal-only prefixes (`00-tracker.md`) for ordered files inside a folder. +- Concurrent stages share a number and differ by a letter: `02a_market`, `02b_competitors`. Same number means no ordering between them; the next integer runs after all of them. The letter is not a priority — `02a` and `02b` are peers, and a run may do them in any order or at once. - Meta/system folders get an underscore prefix and sort to the top: `_meta/`, `_system/`, `_shared/`, `_config/`, `_templates/`, `_index/`, `_archive/`. Underscore = "about the workspace, not of the work." - Records and nodes: kebab-case slugs for machine-facing files, or human-readable Title Case where a person browses daily (an Obsidian vault). Pick one per workspace and write the choice into the schema — drift between schema and files is the most common decay. - Typed content files may prefix their type: `data-customer-list.md`. @@ -87,6 +110,6 @@ Name these honestly rather than overclaiming: - **Real-time multi-agent collaboration** — agents responding to each other in tight loops need message-passing infrastructure; file handoffs are too slow. - **High concurrency** — many users hitting one pipeline needs queueing, state isolation, deployment. ICM is local-first by design. -- **Automated mid-pipeline branching** — a human choosing stage 3a vs 3b between stages is natural; the *system* branching on AI output mid-run pushes ICM toward becoming the framework it replaced. +- **Automated mid-pipeline branching** — a human choosing between two alternative stages at a gate is natural; the *system* branching on AI output mid-run pushes ICM toward becoming the framework it replaced. A fan is not a branch and does not fall under this: every lettered sibling always runs, and the width is fixed when the workspace is written, so nothing is decided at run time. Branching *selects* a path; that selection is where ICM should hand off to framework code. The claim is not that ICM replaces frameworks everywhere. The claim is that for sequential, human-reviewed, repeatable workflows — most knowledge work — the framework is more complexity than the problem requires, and that complexity costs opacity, fragility, and developer dependency. diff --git a/references/forms.md b/references/forms.md index a5681d0..319cc54 100644 --- a/references/forms.md +++ b/references/forms.md @@ -36,6 +36,7 @@ workspace/ - Handoff = one stage's `output/` is the next stage's input. A human edits the file in between; the next stage reads whatever is there. - Each contract carries a "load this / do NOT load that" inputs table. - `status` is answered by scanning `stages/*/output/` for files. +- Independent stages share a number and differ by letter (`02a_`, `02b_`); the stage after them is a join that names all of them in its inputs. Fan only where the work is genuinely unordered, and only two to four wide — the gate is a person's attention, not the machine's. See *Parallel stages and the join* in core.md. - Stage boundaries sit where the human naturally pauses to check — surfacing the judgment call (an outline, a structural plan) as an editable file *before* the expensive downstream work is the whole trick. Correction is cheapest at the earliest gate. **Expect a U-curve of human editing:** heavy at the first stage (direction-setting), light in the middle (constrained by both anchors), heavy at the last (aligning output with earlier decisions). Design the first and last outputs to be especially easy to edit.