From 3d306107aafd7e232139a5e7b381eba28f181126 Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 26 Oct 2026 02:58:48 +0000 Subject: [PATCH] fix: describe the provenance skip where the docs still described the id-only one (ship Step 9.4) The preamble-hoist.ts docblock and ARCHITECTURE.md still said the shared preamble is re-read only when its id is absent; since 2acf1a44a the pointer requires the skill's own earlier Read of the file. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- ARCHITECTURE.md | 2 +- scripts/resolvers/preamble-hoist.ts | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 97b7950f4..6124cc594 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -395,7 +395,7 @@ Most workflow skills start with a `{{PREAMBLE}}` block that runs before the skil 4. **AskUserQuestion format** — universal format: context, question, `RECOMMENDATION: Choose X because ___`, lettered options. Consistent across all skills. 5. **Search Before Building** — before building infrastructure or unfamiliar patterns, search first. Three layers of knowledge: tried-and-true (Layer 1), new-and-popular (Layer 2), first-principles (Layer 3). When first-principles reasoning reveals conventional wisdom is wrong, the agent names the "eureka moment" and logs it. See `ETHOS.md` for the full builder philosophy. -Tier 2+ skills share most of this text, so it is not repeated in each SKILL.md. `scripts/resolvers/preamble-hoist.ts` renders the skill-independent preamble sections once per host into `sections/preamble.md` beside the SKILL.md, and the SKILL.md opens with a short "Shared preamble (load first)" pointer that names the file's content id; the agent reads the file only when that id is not already in the conversation, so a session loads it once. A section moves only when the skill's render of it is byte-identical to the shared render. The start command, sections that name the skill (Question Tuning, Repo Ownership, Search Before Building, Telemetry) and skill-specific variants stay inline. Tier 1 skills keep their short preamble inline. +Tier 2+ skills share most of this text, so it is not repeated in each SKILL.md. `scripts/resolvers/preamble-hoist.ts` renders the skill-independent preamble sections once per host into `sections/preamble.md` beside the SKILL.md, and the SKILL.md opens with a short "Shared preamble (load first)" pointer that names the file's content id; the agent reads the file unless its own earlier Read of that file, headed by that id, is still in context, so a session loads it once and text that merely carries the id never stands in for it. A section moves only when the skill's render of it is byte-identical to the shared render. The start command, sections that name the skill (Question Tuning, Repo Ownership, Search Before Building, Telemetry) and skill-specific variants stay inline. Tier 1 skills keep their short preamble inline. ### Why committed, not generated at runtime? diff --git a/scripts/resolvers/preamble-hoist.ts b/scripts/resolvers/preamble-hoist.ts index 7a7620a6c..4f8d1f743 100644 --- a/scripts/resolvers/preamble-hoist.ts +++ b/scripts/resolvers/preamble-hoist.ts @@ -7,8 +7,9 @@ * tier 2+ SKILL.md. The SKILL.md keeps a pointer to that file and every * preamble section whose text is this skill's own: the start command, any * section that names the skill or has a skill-specific variant, and tier 3's - * additions. The pointer asks for a Read only when the file's marker is not - * already in the conversation, so a session loads it once. + * additions. The pointer asks for a Read unless this skill's own earlier Read + * of that file, headed by its id, is still in context, so a session loads it + * once and text that merely carries the id never stands in for it. * * A section is hoisted only when this skill's render of it is byte-identical * to the shared render, so no skill's instructions change; they move.