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.