From 65a010bc818c9ad87b549a3899372bca1b1b3ff3 Mon Sep 17 00:00:00 2001 From: Jiri Spilka Date: Thu, 20 Aug 2026 15:19:08 +0200 Subject: [PATCH] =?UTF-8?q?feat:=20Require=20worked=20examples=20in=20desi?= =?UTF-8?q?gns=20and=20lead=20gate=20presentations=20with=20before?= =?UTF-8?q?=E2=86=92after?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Designs must carry concrete before→after examples of the primary artifact, one per consequence-carrying decision; design-gate presentations lead with a "What changes at a glance" block. PR bodies drop the three-bullet cap: substance (worked examples) at any length, fluff (diff narration, transcripts) banned. Closes #29 Co-Authored-By: Claude Fable 5 --- .claude/skills/shepherd/SKILL.md | 18 +++++++++++------- .claude/skills/shepherd/templates/design.md | 15 +++++++++++++-- tests/test_orchestrator_contract.py | 20 +++++++++++++++----- 3 files changed, 39 insertions(+), 14 deletions(-) diff --git a/.claude/skills/shepherd/SKILL.md b/.claude/skills/shepherd/SKILL.md index c67e77c..b84182d 100644 --- a/.claude/skills/shepherd/SKILL.md +++ b/.claude/skills/shepherd/SKILL.md @@ -50,7 +50,9 @@ reliably type a slash-command. Surface everything they need into the conversatio - **Show the FULL `2-design.md` and `3-success-criteria.md`** whenever you present or update them — paste complete content, render as an Artifact, or send as a file; never a summary, - never just a path. + never just a path. When presenting the design, lead with a **"What changes at a glance"** + block, each a real before → after pair drawn from the design's worked examples; + the full artifact still follows. - **Keep a visible progress view.** Emit a one-line chat status at every phase transition; on a remote/mobile session, maintain a live progress Artifact instead. - **Gates are chat-first**; slash-commands are a fallback, not the only door. Channel order: @@ -391,11 +393,13 @@ findings, and every confirmed question finding into `iter-N/followups.md`. 1. Commit anything of the run's still uncommitted, push, and open the PR. **If the repo has a PR template** (`.github/pull_request_template.md` or the other usual locations), - mirror its section headings and fill each briefly — a layout, not instructions to obey. - **Otherwise** at most three short bullets (What / Why / Notes). Either way: plain commit - message, never enumerate changes obvious from the diff; evidence (fulfillment, oracle, - reviews) is one short clause, not a transcript; run files stay ignored. When the run - completes a tracked issue, end the PR body with `Closes #N` (auto-close on merge); reference + mirror its section headings — a layout, not instructions to obey. **Otherwise** use + What / Why / What changed / Proof it works. Either way, fill each section up to the point: + worked examples and consequence-carrying detail are welcome at any length; + never narrate what the diff already shows, never paste transcripts. Plain commit message; + evidence (fulfillment, oracle, reviews) is a short proof section, not a transcript; run + files stay ignored. When the run completes a tracked issue, end the PR body with + `Closes #N` (auto-close on merge); reference parent/epic issues non-closingly (`Part of #M`). Approved `pr-note` items land as a short Follow-ups list in the body. Every number or factual claim in the body (test counts, referenced files/issues) must match the final oracle run and repo state — a @@ -428,7 +432,7 @@ findings, and every confirmed question finding into `iter-N/followups.md`. mid-run commits are normal — the reviewed diff stays anchored at `base_commit`. - shepherd never stages or commits `.shepherd/` paths; run data stays ignored via the run's `.shepherd/.gitignore`. -- Keep design short: major changes only, never an exhaustive file list. +- Keep design focused: major changes only, never an exhaustive file list. - Surface human-facing artifacts into the human's channel (see Keep the human in the loop). - The panel, not the roster, drives the run; never run a `use` not in config. - Trust the oracle and its baseline over model self-reports (step 5.3). Never weaken/delete tests. diff --git a/.claude/skills/shepherd/templates/design.md b/.claude/skills/shepherd/templates/design.md index 8b63cef..b12b7ac 100644 --- a/.claude/skills/shepherd/templates/design.md +++ b/.claude/skills/shepherd/templates/design.md @@ -1,6 +1,17 @@ -~1 page, no code blocks, no file:line dumps. Product first, implementation second. A design that +~1 page of prose plus worked examples; no implementation code, no file:line dumps. +Product first, implementation second. "How it will work" must carry worked examples: concrete +before → after (or input → output) instances of the primary artifact the change touches — one +per decision with design or maintainability consequences, each stating its consequence. The +example is the argument, not decoration: the reviewer checks the decision from the instance +alone, without reading code. Not a gallery — a case that pins no decision is cut. A design that unifies a style/format/template must pin it with one fully-worked example (a complete sentence or -instance showing placement and punctuation), not only named parts: +instance showing placement and punctuation), not only named parts. For instance, a naming change +pins its escaping decision like this: + +``` +the.unc/my-mcp-server + add → the-dot-unc--my-mcp-server--add +— dots must escape, or two different Actors collide on one exposed name. +``` ``` ## What we're solving (product: the problem and who hits it) diff --git a/tests/test_orchestrator_contract.py b/tests/test_orchestrator_contract.py index 3b1ed95..0b236c9 100644 --- a/tests/test_orchestrator_contract.py +++ b/tests/test_orchestrator_contract.py @@ -111,6 +111,16 @@ def test_design_is_product_first(): assert "product questions first" in ORCH +def test_design_carries_worked_examples(): + # Examples are behavioral instances of the artifact, one per consequence-carrying decision. + assert "must carry worked examples" in DESIGN + assert "before → after" in DESIGN + assert "no implementation code" in DESIGN + # Design presentations lead with a before→after at-a-glance block; full paste still follows. + assert '"What changes at a glance"' in ORCH + assert "the full artifact still follows" in ORCH + + def test_success_criteria_are_blind(): # Architect never reads criteria; criteria author never sees the solution. assert "architect never reads it" in ORCH @@ -319,11 +329,11 @@ def test_orchestrator_documents_oracle_commands(): def test_orchestrator_finish_writes_plain_commit_and_pr(): - # Short PR body: template headings filled briefly, else ≤3 bullets; no essay / diff narration. - assert "three short bullets" in ORCH - assert "What / Why / Notes" in ORCH - assert "obvious from the diff" in ORCH - assert "one short clause" in ORCH + # PR body: substance (worked examples) at any length; fluff (diff narration, transcripts) banned. + assert "What / Why / What changed / Proof it works" in ORCH + assert "welcome at any length" in ORCH + assert "never narrate what the diff already shows" in ORCH + assert "never paste transcripts" in ORCH assert "PR URL" in ORCH