Problem
The design gate presents ~1 page of abstract prose. In the #27 restructure run, 2-design.md described moving prose between files for 130 lines without a single concrete instance of what a reader sees before vs after (e.g. one role-table row, or one dispatch-prompt fragment, pre- and post-split). The human at the gate had to trust descriptions, then reverse-engineer the actual change from the diff much later. Long runs make this worse: the design is the one artifact the human must genuinely absorb, and it is currently the hardest one to skim.
templates/design.md already mandates a fully-worked example — but only for designs that unify a style/format/template. Every other design may ship example-free.
Proposal
templates/design.md — generalize the worked-example rule: "How it will work" must include one worked example: a concrete before → after instance of the primary artifact the change touches (a file excerpt, command output, or prompt fragment), not only prose about it. One example, not a gallery (the style-unification rule already covers the case needing a pinned format).SKILL.md, "Keep the human in the loop" — when presenting the design (iterate step and design gate), precede the FULL paste with a "What changes at a glance" block: ≤5 bullets, each a real before → after pair drawn from the design's example. The full artifact remains the record; summary-only presentations stay banned.- Contract tests — pin the new template sentence on the
DESIGN constant and the presentation rule on ORCH.
Verification
The next real run's 2-design.md carries the example, and its gate message leads with the at-a-glance block.
Ordering
After #27's PR lands (it creates the templates/design.md this edits). Small tier — a few lines in two files plus two test pins.
Problem
The design gate presents ~1 page of abstract prose. In the #27 restructure run,
2-design.mddescribed moving prose between files for 130 lines without a single concrete instance of what a reader sees before vs after (e.g. one role-table row, or one dispatch-prompt fragment, pre- and post-split). The human at the gate had to trust descriptions, then reverse-engineer the actual change from the diff much later. Long runs make this worse: the design is the one artifact the human must genuinely absorb, and it is currently the hardest one to skim.templates/design.mdalready mandates a fully-worked example — but only for designs that unify a style/format/template. Every other design may ship example-free.Proposal
templates/design.md— generalize the worked-example rule: "How it will work" must include one worked example: a concrete before → after instance of the primary artifact the change touches (a file excerpt, command output, or prompt fragment), not only prose about it. One example, not a gallery (the style-unification rule already covers the case needing a pinned format).SKILL.md, "Keep the human in the loop" — when presenting the design (iterate step and design gate), precede the FULL paste with a "What changes at a glance" block: ≤5 bullets, each a realbefore → afterpair drawn from the design's example. The full artifact remains the record; summary-only presentations stay banned.DESIGNconstant and the presentation rule onORCH.Verification
The next real run's
2-design.mdcarries the example, and its gate message leads with the at-a-glance block.Ordering
After #27's PR lands (it creates the
templates/design.mdthis edits). Small tier — a few lines in two files plus two test pins.