shape · diff

git:20261114.052ab81 to git:20261114.fa8b3c3

51 added, 42 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: shape
- description: Use when the user runs /galdr:shape to turn a fuzzy idea, a position to stress-test, or settled requirements into the goal and decisions of a plan.
+ description: Use when the user runs /galdr:shape to turn an idea, a position to test, or clear requirements into the goal and decisions of a plan.
disable-model-invocation: true
---
# shape
- Writes the what and why of an idea as the top half of its plan file,
- `docs/plans/<YYYY-MM-DD>-<topic>.md`.
+ shape writes the what and the why of an idea. It writes them as the top half of the plan
+ file, `docs/plans/<YYYY-MM-DD>-<topic>.md`.
- ## Pick a mode
+ ## Select a mode
- - Requirements already settled → **synthesis**: no questions, write the plan's top half.
- - A position to stress-test ("grill me") → **grill**.
- - No position yet → **explore**.
+ - The user has clear requirements: use **synthesis**. Ask no questions. Write the top half.
+ - The user has a position to test ("grill me"): use **grill**.
+ - The user has no position yet: use **explore**.
- ## Settle facts by trying, not asking
+ ## Find facts yourself
- Before each question, check whether reading the code, docs or config, or running
- something, answers it. Such a fact goes into the plan with its source; it is never
- asked. Only decisions, choices among options that change what gets built, reach the
- user.
+ Before each question, find out if the code, docs, config or a command can answer it.
+ Write such a fact into the plan with its source. Never ask the user for it. Ask the user
+ only about decisions: choices that change the result.
## Question budget
- - One question per message, never a list.
- - Recommendation first: your pick and its one-line reason, then the question.
+ - Ask one question in each message. Never ask a list.
+ - Give your recommendation first, with a one-line reason. Then ask the question.
```
Next: do "reviews" mean buyer reviews of a storefront, or reviews of the platform?
- Recommend buyer reviews of a storefront: that noun is already in use, and platform
- reviews are not a stated need.
+ Recommend buyer reviews of a storefront. That noun is already in use, and nobody
+ asked for platform reviews.
```
- - Synthesis and explore ask at most 3 questions before the draft. Every decision still
- open goes into the plan as an assumption carrying your recommended choice.
- - Grill was asked for questions: keep going, one at a time, until the tree is resolved
- or the user stops.
- - Default to the simplest design that meets the stated need. A heavier option (queue,
- outbox, new service, new abstraction) appears only as a rejected alternative with its
- reason, unless the user asked for it.
+ - In synthesis and explore, ask at most 3 questions before the draft. Each open decision
+ goes into the plan as an assumption with your recommended choice.
+ - In grill, the user asked for questions. Continue one at a time until the tree has no
+ open branch, or until the user stops.
+ - Prefer the simplest design that meets the stated need. Show a heavier option (queue,
+ outbox, new service, new abstraction) only as a rejected alternative with its reason,
+ unless the user asked for it.
## Grill
- 1. List the open decisions as a tree ordered by dependency: an early answer can change
+ 1. List the open decisions as a tree in order of dependency. An early answer can change
the later questions.
- 2. Ask them in that order, under the budget above.
- 3. Write each confirmed decision into the plan's Decisions table as it lands,
- creating the file at the first one, so a session that dies loses nothing.
- 4. Done when every branch is decided or deferred with a named owner. Then synthesis.
+ 2. Ask them in that order, within the budget.
+ 3. Write each decision that the user accepts into the Decisions table immediately. Make
+ the file at the first decision. Then a session that stops loses nothing.
+ 4. The grill is complete when each branch has a decision, or an owner for a later
+ decision. Then do synthesis.
## Explore
- 1. Read the project's instructions and the existing code before proposing anything.
- 2. If the request spans several subsystems, name each one's slice before designing any.
- 3. For each slice, give 2 or 3 approaches, recommendation first, then the trade-offs.
- 4. Open questions left in a slice follow the budget. Then synthesis.
+ 1. Read the instructions of the project and the existing code before you propose
+ anything.
+ 2. If the request covers many subsystems, name the part for each subsystem before you
+ design any part.
+ 3. For each part, give 2 or 3 approaches. Give your recommendation first, then the
+ trade-offs.
+ 4. For an uncertain design with a durable effect, one read-only architect subagent can
+ give advice. The decision stays with you and the user.
+ 5. Open questions in a part follow the budget. Then do synthesis.
## Synthesis
- Write the plan's top half in the format of `skills/galdr/references/plan-format.md`:
- title, status line (`draft · next: /galdr`), header, Goal, Out of scope, Done when, and
- Decisions with each choice's why, trade-off and source. Add Design only when the
- discussion settled it.
+ Write the top half of the plan in the format of `skills/galdr/references/plan-format.md`.
+ Write these sections:
- Then fix inline, before showing it:
+ - the title and the status line (`draft · next: /galdr`)
+ - the header
+ - Goal, Out of scope and Done when
+ - Decisions, with the reason, trade-off and source of each choice
- 1. Placeholders: no "TBD", "handle edge cases" or "similar to X".
+ Add Design only when the discussion settled it. Then examine the draft and fix these
+ problems before you show it:
+
+ 1. Placeholders: "TBD", "handle edge cases" or "similar to X".
2. Contradictions between sections.
- 3. Scope: no more and no less than was asked.
- 4. Ambiguity: if two readers could build it two ways, sharpen it.
+ 3. Scope: more or less than the user asked for.
+ 4. Ambiguity: two readers can build it in two ways. Make it exact.
## End
- shape writes no tasks and no code. End with "Next: run `/galdr` to add the tasks; you
+ shape writes no tasks and no code. End with "Next: run `/galdr` to add the tasks. You
approve the whole plan once, before any code."
- Done when the plan file has these sections and passes the four checks.
+ shape is complete when the plan file has these sections and passes the four checks.