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>
This commit is contained in:
garrytanandcapy-ai[bot] committed 2026-10-26 02:58:48 +00:00
1 parent ebb8f9f8e6
commit 3d306107aa
2 files changed
+4 -3

No files matched your search

+1 -1
View File
@@ -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?
+3 -2
View File
@@ -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.