mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-01 19:25:10 +02:00
v1.10.0.0: fix AskUserQuestion cadence + Pros/Cons format upgrade (#1178)
* fix(preamble): reorder AskUserQuestion Format above model overlay + rewrite Opus 4.7 pacing directive
Root cause of plan-review regression (v1.6.4.0): model overlays rendered
ABOVE the pacing rule in every SKILL.md, so Opus 4.7 read "Batch your
questions" first and absorbed it as the ambient default. The overlay's
claimed subordination ("skill wins on pacing, always") didn't stick —
literal-interpretation mode reads physical order, not claimed hierarchy.
Part 1 of 4 (plan: ~/.claude/plans/system-instruction-you-are-working-polymorphic-twilight.md):
scripts/resolvers/preamble.ts
- Move generateAskUserFormat above generateModelOverlay in section array
- Comment explains why — prevents future refactors from silently reverting
model-overlays/opus-4-7.md
- Replace "Batch your questions" block with "Pace questions to the skill"
- New wording makes one-question-per-turn the default when the skill
contains STOP directives; batching becomes the explicit exception
Regenerated 30 SKILL.md files via bun run gen:skill-docs.
Verified:
- With --model opus-4-7: Format renders at line 359, Model-Specific
Patch at 373, "Pace questions" at 419 (Format comes first, overlay
second, pacing directive intact).
- bun test passes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(plan-reviews): tighten STOP/escape-hatch directives across 4 templates
Part 2 of 4 (plan: ~/.claude/plans/system-instruction-you-are-working-polymorphic-twilight.md).
Codex caught that v1.6.3.0's reasoning collapsed on Opus 4.7: the old
escape-hatch wording ("If no issues or fix is obvious, state what
you'll do and move on — don't waste a question") let the literal
interpreter classify every finding as having an "obvious fix" and skip
AskUserQuestion entirely. Reviews became reports.
Per-template hardening (16 sites total, verified by rg):
plan-ceo-review/SKILL.md.tmpl (13 sites):
- 12 inline STOP directives: replace the full escape-hatch clause with
"zero findings → say so and proceed; findings → MUST call AskUserQuestion
as a tool_use, including for obvious fixes."
- 1 Escape hatch bullet in CRITICAL RULE section: tightened.
plan-eng-review, plan-design-review, plan-devex-review (1 site each):
- Each template's Escape hatch bullet tightened to match the new CEO wording,
adapted for each review's domain (issue/gap, decision/design/DX alternatives).
After regeneration: rg "don't waste a question" returns 0 across all
*SKILL.md.tmpl and *SKILL.md files. "zero findings, state" wording
present 16 times (matches prior count of escape-hatch sites).
bun test passes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(preamble): upgrade AskUserQuestion format to Pros/Cons decision brief
Part 4 of 4 (plan: ~/.claude/plans/system-instruction-you-are-working-polymorphic-twilight.md).
Every AskUserQuestion now renders as a decision brief, not a bullet list:
D-numbered header, ELI10, Stakes-if-we-pick-wrong, Recommendation, Pros/Cons
with ✅/❌ markers per option, closing Net: tradeoff synthesis.
scripts/resolvers/preamble/generate-ask-user-format.ts
- Full rewrite. Preserves prior rules (Re-ground, ELI10, Recommend,
Completeness, Options) and adds:
- D-numbering per skill invocation (model-level, not runtime state)
- Stakes line (pain avoided / capability unlocked / consequence named)
- Pros/Cons block with min 2 ✅ + 1 ❌ per option, min 40 chars/bullet
- Hard-stop escape: "✅ No cons — this is a hard-stop choice" for
genuine one-sided choices (destructive-action confirmations)
- Neutral-posture handling (CT1-compliant): (recommended) label
STAYS on default option to preserve AUTO_DECIDE contract; neutrality
expressed as prose in Recommendation line only
- Net line closes the decision with a one-sentence tradeoff frame
- Rule 11: tool_use mandate (prose "Question:" blocks don't count)
- Self-check list before emitting
test/skill-validation.test.ts
- Update format assertions to check for new Pros/Cons tokens
(Pros / cons:, Recommendation: <choice>, Net:, ELI10, Stakes if we
pick wrong:, ✅, ❌) across all tier-2+ skills
- Old "RECOMMENDATION: Choose" expectation removed (the new format uses
mixed-case "Recommendation:" with no literal "Choose")
test/skill-e2e-plan-format.test.ts
- Add v1.7.0.0 format token regexes (PROS_CONS_HEADER_RE, PRO_BULLET_RE,
CON_BULLET_RE, NET_LINE_RE, D_NUMBER_RE, STAKES_RE)
- Existing RECOMMENDATION_RE loosened to accept mixed-case "Recommendation:"
(canonical v1.7.0.0 form) alongside all-caps (legacy). Tests are
additive — the strict new-format gate is the upcoming cadence eval.
Regenerated 30 SKILL.md files via bun run gen:skill-docs.
Verified:
- bun test: 319 pass (1 pre-existing security-bench fixture oversize
failure on main, unrelated — confirmed via git stash test on main HEAD)
- New format tokens render in all tier-2+ skills (plan-ceo-review,
plan-eng-review, ship, office-hours verified)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: gate-tier units + periodic Pros/Cons evals for AskUserQuestion format
Part 3 of 4 (plan: ~/.claude/plans/system-instruction-you-are-working-polymorphic-twilight.md).
Gate-tier (E1, free, runs on every `bun test`):
test/preamble-compose.test.ts — pins the composition order
Asserts AskUserQuestion Format section renders BEFORE Model-Specific
Behavioral Patch in tier-≥2 preamble output. Covers claude default,
opus-4-7 overlay, tier 2/3, and codex host. Catches any future edit
to scripts/resolvers/preamble.ts that silently reverts the order.
test/resolver-ask-user-format.test.ts — pins the Pros/Cons contract
14 assertions against generateAskUserFormat output: D<N>, ELI10,
Stakes if we pick wrong:, Recommendation: <choice>, Pros / cons:,
✅/❌ markers, min 2 pros + 1 con rules, hard-stop escape exact
phrase, neutral-posture CT1 rule ((recommended) label preserved for
AUTO_DECIDE), Completeness coverage-vs-kind, tool_use mandate
(rule 11), self-check list, D-numbering model-level caveat.
test/model-overlay-opus-4-7.test.ts — pins the pacing directive
Asserts raw overlay file + resolved overlay output contain "Pace
questions to the skill" and NOT "Batch your questions". Verifies
INHERIT:claude chain still works (Todo-list, subordination wrapper),
Fan out / Effort-match / Literal interpretation nudges preserved.
Also asserts claude base overlay does NOT carry the Opus-specific
pacing directive (no cross-contamination).
Periodic-tier (E2, Opus-dependent, ~$1-2/run):
test/skill-e2e-plan-prosons.test.ts — 4 cases extending v1.6.3.0 harness
1. Format positive — every token present when plan has real tradeoff
2. Hard-stop NEGATIVE — plan with genuine tradeoff must NOT dodge to
"No cons — hard-stop choice" escape
3. Neutral-posture NEGATIVE — plan where one option dominates must emit
(recommended) label + "because <reason>", must NOT dodge to
"taste call" / "no preference"
4. Hard-stop POSITIVE — destructive-action plan may legitimately use
the hard-stop escape
test/helpers/touchfiles.ts — entries for all new eval cases
Dependencies: overlay, preamble.ts, generate-ask-user-format.ts, and
the 4 plan-review templates. Diff-based selection triggers the evals
whenever those files change. Also added entries for 7 expanded-coverage
cases (ship, office-hours, investigate, qa, review, design-review,
document-release) — test cases will land in follow-up PRs per skill.
Follow-ups noted in test file header:
- True multi-turn cadence eval (3 findings → 3 distinct asks) — current
harness captures one $OUT_FILE per session; multi-turn capture needs
new harness support.
- Expanded-coverage test cases for the 7 non-plan-review skills.
Verified:
- bun test: 349 pass (30 new + 319 baseline), 1 pre-existing security-bench
oversize failure on main (unrelated, unchanged).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: regenerate golden fixtures + update ELI10 phrase check for v1.7.0.0
Pros/Cons format rewrite (6b99df9d) changed the resolver output across all
tier-2+ SKILL.md files. Three golden-file regression tests in
test/host-config.test.ts and one phrase-check test in test/gen-skill-docs.test.ts
were failing as expected.
- test/fixtures/golden/claude-ship-SKILL.md
- test/fixtures/golden/codex-ship-SKILL.md
- test/fixtures/golden/factory-ship-SKILL.md
Regenerated via `bun run gen:skill-docs --host all` + cp into fixtures.
- test/gen-skill-docs.test.ts line 244: rename test from "ELI16 simplification
rules" to "ELI10 simplification rules" and match the new phrase pattern.
v1.7.0.0 uses "ELI10 (ALWAYS)" rather than legacy "Simplify (ELI10, ALWAYS)".
bun test: 744 pass, 1 fail (pre-existing security-bench fixture oversize,
unrelated to this branch).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* v1.7.0.0: plan reviews walk you through each issue with Pros/Cons
Restores AskUserQuestion cadence on Opus 4.7 (v1.6.4.0 regression) and
upgrades the format to a numbered decision brief — D<N> header, ELI10,
Stakes, Recommendation, per-option ✅/❌ bullets, Net: closing line.
Fix: composition reorder + overlay rewrite + 16-site escape-hatch hardening
across the 4 plan-review templates.
Feature: Pros/Cons format in the preamble resolver, inherited by every
tier-2+ skill automatically.
30 new gate-tier unit tests pin the format contract (runs in <100ms, $0).
4 new periodic-tier eval cases defend against escape-hatch abuse
(2 positive, 2 negative). Golden fixtures regenerated.
CEO + Eng + Codex reviews completed. 5 of 8 Codex findings incorporated;
CT2 (16 sites, not 31) and CT1 (AUTO_DECIDE contract break) were
load-bearing catches the primary reviews missed.
bun test: 774 pass, 1 fail (pre-existing security-bench oversize, unrelated).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* v1.10.0.0: bump VERSION (was v1.7.0.0, align with branch discipline)
Per user direction — jumping to 1.10.0.0 for versioning alignment.
No functional changes from the prior ship commit (5f038ab7). The
regression fix + Pros/Cons format are identical.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -1,5 +1,62 @@
|
||||
# Changelog
|
||||
|
||||
## [1.10.0.0] - 2026-04-23
|
||||
|
||||
## **Plan reviews walk you through each issue again, and every question is now a real decision brief.**
|
||||
|
||||
v1.6.4.0 broke something nobody wrote down. Plan reviews on Opus 4.7 silently stopped asking questions one at a time. They turned into a report: here are 6 findings, end of turn. The interactive dialogue that made `/plan-ceo-review`, `/plan-eng-review`, and the rest useful quietly evaporated. v1.10.0.0 restores that, and bundles a format upgrade so every `AskUserQuestion` now renders as a numbered decision brief with ELI10, stakes, recommendation, per-option pros / cons (✅ / ❌), and a closing "Net:" line that frames the trade-off in one sentence.
|
||||
|
||||
### What changes for you
|
||||
|
||||
Run `/plan-ceo-review` or `/plan-eng-review` on a plan with 3 findings. You get 3 separate AskUserQuestion prompts, one per finding, with the full Pros / Cons shape. Pick the option in 5 seconds, or expand the pros / cons if you want to think about it. Every review finding becomes a decision you actually made, not a bullet point you skimmed. The reference shape matches the D2 memory-design question Garry hand-crafted for his own use, now baked into every tier-2 skill via the preamble resolver, so `/ship`, `/office-hours`, `/investigate`, and the rest inherit it for free.
|
||||
|
||||
### The numbers that matter
|
||||
|
||||
Measured across the v1.10.0.0 fix. Verify any claim with `git log 1.9.0.0..1.10.0.0 --oneline` and `bun test` against the pinned commit SHA.
|
||||
|
||||
| Metric | v1.6.4.0 | v1.10.0.0 | Δ |
|
||||
|---|---|---|---|
|
||||
| `AskUserQuestion` renders above model overlay in SKILL.md | no | **yes** | ordering inverted |
|
||||
| Escape-hatch sites hardened across plan-review templates | 0 | **16** | +16 |
|
||||
| Gate-tier unit tests pinning the format contract | 0 | **30** | +30 (runs in 16ms, $0) |
|
||||
| Periodic evals defending against escape-hatch abuse | 0 | **4** | +4 (2 positive, 2 negative-case) |
|
||||
| Cross-model review findings incorporated before landing | N/A | **5 of 8** | Codex caught real bugs CEO+Eng missed |
|
||||
|
||||
Two of the five Codex findings were load-bearing. (1) The overlay reorder theory wasn't enough on its own. The `(recommended)` label on a neutral-posture question had to stay, because `question-tuning.ts:29` reads it to power AUTO_DECIDE. Omitting it would have silently broken auto-decide on every cherry-pick prompt. (2) The "31 sites global replace" in the original plan was factually wrong. Actual count, verified with `rg`, is 16 sites across 4 templates, and eng/design/devex templates used different phrasing than CEO. Without the audit, the fix would have shipped half-applied.
|
||||
|
||||
### What this means for anyone running plan reviews on Opus 4.7
|
||||
|
||||
Upgrade and re-run your next plan review. You should see D-numbered prompts (D1, D2, D3...) with ELI10 paragraphs, stakes lines, and ✅ / ❌ bullet blocks per option. If you don't, check that `bun run gen:skill-docs` regenerated cleanly after the upgrade, and verify the `Pros / cons:` header renders in `plan-ceo-review/SKILL.md`. Complete plan reviews that used to take 20 minutes and produced a report now take 10 minutes and produce a row of decisions.
|
||||
|
||||
### Itemized changes
|
||||
|
||||
#### Added
|
||||
|
||||
- New Pros / Cons decision-brief format for every `AskUserQuestion` across all tier-2+ skills. Rendering: `D<N>` header, ELI10, "Stakes if we pick wrong:", Recommendation, per-option `✅ / ❌` bullets with minimum 2 pros + 1 con, closing `Net:` synthesis line. Lands in `scripts/resolvers/preamble/generate-ask-user-format.ts` so every skill inherits it.
|
||||
- Hard-stop escape for destructive one-way choices: single bullet `✅ No cons — this is a hard-stop choice`.
|
||||
- Neutral-posture handling for SELECTIVE EXPANSION cherry-picks and taste calls: `Recommendation: <default> — this is a taste call, no strong preference either way` with `(recommended)` label preserved on the default to keep AUTO_DECIDE working.
|
||||
- Three gate-tier unit tests (`test/preamble-compose.test.ts`, `test/resolver-ask-user-format.test.ts`, `test/model-overlay-opus-4-7.test.ts`) that pin the composition order, format contract, and overlay text. Run in <100ms on every `bun test`.
|
||||
- Four periodic-tier Pros/Cons eval cases in `test/skill-e2e-plan-prosons.test.ts` including two negative-case assertions that catch escape-hatch abuse before it drifts.
|
||||
- Touchfiles entries (`test/helpers/touchfiles.ts`) for all new eval cases plus expanded-coverage stubs for 7 additional skills.
|
||||
|
||||
#### Fixed
|
||||
|
||||
- Plan-review cadence regression on Opus 4.7. `/plan-ceo-review`, `/plan-eng-review`, `/plan-design-review`, and `/plan-devex-review` now actually pause after each finding and call `AskUserQuestion` as a tool_use instead of batching everything into one summary report. Root cause: `generateModelOverlay` rendered above `generateAskUserFormat` in `scripts/resolvers/preamble.ts`, so the overlay's "Batch your questions" directive registered as the ambient default before the pacing rule. Fixed by reordering the section array and rewriting the overlay directive as "Pace questions to the skill".
|
||||
- Escape-hatch collapse: "If no issues or fix is obvious, state what you'll do and move on, don't waste a question" at 16 sites across 4 templates let Opus 4.7's literal interpreter classify every finding as self-dismissable. Tightened per-template: zero findings gets "No issues, moving on"; findings require AskUserQuestion as a tool_use.
|
||||
|
||||
#### Changed
|
||||
|
||||
- `test/skill-e2e-plan-format.test.ts`: extended with v1.10.0.0 format token regexes (D-number, ELI10, Stakes, Pros/cons, Net). Existing RECOMMENDATION check loosened to accept mixed-case "Recommendation:".
|
||||
- `test/skill-validation.test.ts`: format assertions updated from "RECOMMENDATION: Choose" to the new Pros/Cons token set.
|
||||
- Golden fixtures regenerated: `test/fixtures/golden/claude-ship-SKILL.md`, `codex-ship-SKILL.md`, `factory-ship-SKILL.md`.
|
||||
|
||||
#### For contributors
|
||||
|
||||
- Outside-voice Codex review (`codex exec` with `model_reasoning_effort="high"`) caught two factual bugs in the original plan: the "31 sites" count (actually 16) and the AUTO_DECIDE contract break on neutral-posture questions. 5 of 8 Codex findings incorporated, 1 rejected (kept defense in depth on the composition reorder), 1 declined (HOLD SCOPE mode lock).
|
||||
- Follow-up: true multi-turn cadence eval (3 findings produce 3 distinct AskUserQuestion invocations across turns) requires new harness support for multi-capture. Filed in NOT-in-scope. Current single-capture eval covers format + escape-hatch abuse but not cadence itself.
|
||||
- Follow-up: expanded-coverage eval cases for `/ship`, `/office-hours`, `/investigate`, `/qa`, `/review`, `/design-review`, `/document-release`. Touchfiles entries exist; test blocks will land per-skill in follow-up PRs.
|
||||
- D-numbering is a model-level instruction, not a runtime counter. `TemplateContext` has no state for it. Drift over long sessions is expected; a registry (deferred to TODOs) is the long-term fix.
|
||||
|
||||
## [1.9.0.0] - 2026-04-23
|
||||
|
||||
## **Your gstack memory now travels with you. Cross-machine brain via a private git repo + optional GBrain indexing, no daemon, no credential leaks.**
|
||||
@@ -75,6 +132,7 @@ Work on the laptop Monday. Switch to the desktop Tuesday. Skill preamble sees th
|
||||
- `test/brain-sync.test.ts` — 12 of 27 tests pass on first bun-test run; remaining 15 hit bun-test's 5s default timeout (spawnSync-heavy git operations). Behaviors verified via integration smokes during implementation. Test infrastructure needs a 30s per-test timeout wrapper.
|
||||
- Three unmerged team-sync branches (`garrytan/team-supabase-store`, `garrytan/fix-team-setup`, `garrytan/team-install-mode`) should be formally closed if team-sync isn't landing — flagged in the CEO plan.
|
||||
- Pre-existing golden-file regression test failure in `test/host-config.test.ts` (Codex ship skill baseline) exists on `main` too — unrelated to this PR, tracked separately.
|
||||
|
||||
## [1.6.4.0] - 2026-04-22
|
||||
|
||||
## **Sidebar prompt-injection defense got half as noisy, half as trusting of any single classifier.**
|
||||
|
||||
+129
-14
@@ -358,6 +358,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -570,20 +699,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -350,6 +350,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -562,20 +691,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -352,6 +352,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -564,20 +693,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -354,6 +354,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -566,20 +695,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -354,6 +354,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -566,20 +695,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -355,6 +355,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -567,20 +696,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -355,6 +355,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -567,20 +696,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -357,6 +357,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -569,20 +698,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -355,6 +355,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -567,20 +696,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -352,6 +352,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -564,20 +693,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -355,6 +355,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -567,20 +696,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -352,6 +352,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -564,20 +693,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -352,6 +352,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -564,20 +693,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -369,6 +369,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -581,20 +710,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -349,6 +349,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -561,20 +690,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -352,6 +352,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -564,20 +693,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
@@ -28,12 +28,13 @@ extended thinking for genuinely hard subproblems: architectural tradeoffs, subtl
|
||||
security implications, design decisions with competing constraints. Over-thinking
|
||||
simple steps wastes tokens and time.
|
||||
|
||||
**Batch your questions.** If you need to clarify multiple things before proceeding,
|
||||
ask all of them in a single AskUserQuestion turn. Do not drip-feed one question per
|
||||
turn. Three questions in one message beats three back-and-forth exchanges. Exception:
|
||||
skill workflows that explicitly require one-question-at-a-time pacing (e.g., plan
|
||||
review skills with "STOP. AskUserQuestion once per issue. Do NOT batch.") override this
|
||||
nudge. The skill wins on pacing, always.
|
||||
**Pace questions to the skill.** If the current skill's text contains
|
||||
`STOP. AskUserQuestion` anywhere, pace one question per turn — emit the question as
|
||||
a tool_use, stop, wait for the user's response, then continue. Do not batch. A
|
||||
finding with an "obvious fix" is still a finding and still needs user approval
|
||||
before it lands in the plan. Only batch clarifying questions upfront when (a) the
|
||||
skill has no `STOP. AskUserQuestion` directive AND (b) you need multiple unrelated
|
||||
clarifications before you can begin. When in doubt, ask one question per turn.
|
||||
|
||||
**Literal interpretation awareness.** Opus 4.7 interprets instructions literally and
|
||||
will not silently generalize. When the user says "fix the tests," fix all failing tests
|
||||
|
||||
+129
-14
@@ -360,6 +360,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -572,20 +701,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -349,6 +349,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -561,20 +690,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "gstack",
|
||||
"version": "1.9.0.0",
|
||||
"version": "1.10.0.0",
|
||||
"description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
|
||||
"license": "MIT",
|
||||
"type": "module",
|
||||
|
||||
+129
-14
@@ -350,6 +350,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -562,20 +691,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+142
-27
@@ -356,6 +356,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -568,20 +697,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
@@ -1483,7 +1598,7 @@ Once selected, commit fully. Do not silently drift.
|
||||
|
||||
Present these mode options via AskUserQuestion using the preamble's AskUserQuestion Format section: include RECOMMENDATION. These options differ in kind (review posture), not coverage — do NOT emit `Completeness: N/10` per option. Include the one-line note from step 4 of the preamble format rule instead: `Note: options differ in kind, not coverage — no completeness score.`
|
||||
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
## Review Sections (11 sections, after scope and mode are agreed)
|
||||
@@ -1513,7 +1628,7 @@ Evaluate and diagram:
|
||||
**SELECTIVE EXPANSION:** If any accepted cherry-picks from Step 0D affect the architecture, evaluate their architectural fit here. Flag any that create coupling concerns or don't integrate cleanly — this is a chance to revisit the decision with new information.
|
||||
|
||||
Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 2: Error & Rescue Map
|
||||
@@ -1543,7 +1658,7 @@ Rules for this section:
|
||||
* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
|
||||
* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
|
||||
* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 3: Security & Threat Model
|
||||
@@ -1559,7 +1674,7 @@ Evaluate:
|
||||
* Audit logging. For sensitive operations: is there an audit trail?
|
||||
|
||||
For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 4: Data Flow & Interaction Edge Cases
|
||||
@@ -1596,7 +1711,7 @@ For each node: what happens on each shadow path? Is it tested?
|
||||
| Queue backs up 2 hours | ? |
|
||||
```
|
||||
Flag any unhandled edge case as a gap. For each gap, specify the fix.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 5: Code Quality Review
|
||||
@@ -1609,7 +1724,7 @@ Evaluate:
|
||||
* Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
|
||||
* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
|
||||
* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 6: Test Review
|
||||
@@ -1650,7 +1765,7 @@ Flakiness risk: Flag any test depending on time, randomness, external services,
|
||||
Load/stress test requirements: For any new codepath called frequently or processing significant data.
|
||||
|
||||
For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 7: Performance Review
|
||||
@@ -1662,7 +1777,7 @@ Evaluate:
|
||||
* Background job sizing. For every new job: worst-case payload, runtime, retry behavior?
|
||||
* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
|
||||
* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 8: Observability & Debuggability Review
|
||||
@@ -1679,7 +1794,7 @@ Evaluate:
|
||||
|
||||
**EXPANSION and SELECTIVE EXPANSION addition:**
|
||||
* What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.)
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 9: Deployment & Rollout Review
|
||||
@@ -1695,7 +1810,7 @@ Evaluate:
|
||||
|
||||
**EXPANSION and SELECTIVE EXPANSION addition:**
|
||||
* What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.)
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 10: Long-Term Trajectory Review
|
||||
@@ -1711,7 +1826,7 @@ Evaluate:
|
||||
* What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory?
|
||||
* Platform potential. Does this create capabilities other features can leverage?
|
||||
* (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 11: Design & UX Review (skip if no UI scope detected)
|
||||
@@ -1734,7 +1849,7 @@ Evaluate:
|
||||
Required ASCII diagram: user flow showing screens/states and transitions.
|
||||
|
||||
If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
## Outside Voice — Independent Plan Challenge (optional, recommended)
|
||||
@@ -1892,7 +2007,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for
|
||||
* For each option: effort, risk, and maintenance burden in one line.
|
||||
* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference.
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs.
|
||||
* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
|
||||
@@ -376,7 +376,7 @@ Once selected, commit fully. Do not silently drift.
|
||||
|
||||
Present these mode options via AskUserQuestion using the preamble's AskUserQuestion Format section: include RECOMMENDATION. These options differ in kind (review posture), not coverage — do NOT emit `Completeness: N/10` per option. Include the one-line note from step 4 of the preamble format rule instead: `Note: options differ in kind, not coverage — no completeness score.`
|
||||
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
## Review Sections (11 sections, after scope and mode are agreed)
|
||||
@@ -406,7 +406,7 @@ Evaluate and diagram:
|
||||
**SELECTIVE EXPANSION:** If any accepted cherry-picks from Step 0D affect the architecture, evaluate their architectural fit here. Flag any that create coupling concerns or don't integrate cleanly — this is a chance to revisit the decision with new information.
|
||||
|
||||
Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 2: Error & Rescue Map
|
||||
@@ -436,7 +436,7 @@ Rules for this section:
|
||||
* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
|
||||
* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
|
||||
* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 3: Security & Threat Model
|
||||
@@ -452,7 +452,7 @@ Evaluate:
|
||||
* Audit logging. For sensitive operations: is there an audit trail?
|
||||
|
||||
For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 4: Data Flow & Interaction Edge Cases
|
||||
@@ -489,7 +489,7 @@ For each node: what happens on each shadow path? Is it tested?
|
||||
| Queue backs up 2 hours | ? |
|
||||
```
|
||||
Flag any unhandled edge case as a gap. For each gap, specify the fix.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 5: Code Quality Review
|
||||
@@ -502,7 +502,7 @@ Evaluate:
|
||||
* Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
|
||||
* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
|
||||
* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 6: Test Review
|
||||
@@ -543,7 +543,7 @@ Flakiness risk: Flag any test depending on time, randomness, external services,
|
||||
Load/stress test requirements: For any new codepath called frequently or processing significant data.
|
||||
|
||||
For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 7: Performance Review
|
||||
@@ -555,7 +555,7 @@ Evaluate:
|
||||
* Background job sizing. For every new job: worst-case payload, runtime, retry behavior?
|
||||
* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
|
||||
* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 8: Observability & Debuggability Review
|
||||
@@ -572,7 +572,7 @@ Evaluate:
|
||||
|
||||
**EXPANSION and SELECTIVE EXPANSION addition:**
|
||||
* What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.)
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 9: Deployment & Rollout Review
|
||||
@@ -588,7 +588,7 @@ Evaluate:
|
||||
|
||||
**EXPANSION and SELECTIVE EXPANSION addition:**
|
||||
* What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.)
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 10: Long-Term Trajectory Review
|
||||
@@ -604,7 +604,7 @@ Evaluate:
|
||||
* What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory?
|
||||
* Platform potential. Does this create capabilities other features can leverage?
|
||||
* (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones?
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
### Section 11: Design & UX Review (skip if no UI scope detected)
|
||||
@@ -627,7 +627,7 @@ Evaluate:
|
||||
Required ASCII diagram: user flow showing screens/states and transitions.
|
||||
|
||||
If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
|
||||
**Reminder: Do NOT make any code changes. Review only.**
|
||||
|
||||
{{CODEX_PLAN_REVIEW}}
|
||||
@@ -651,7 +651,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for
|
||||
* For each option: effort, risk, and maintenance burden in one line.
|
||||
* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference.
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs.
|
||||
* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
|
||||
+130
-15
@@ -353,6 +353,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -565,20 +694,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
@@ -1721,7 +1836,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for
|
||||
* Present 2-3 options. For each: effort to specify now, risk if deferred.
|
||||
* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an obvious fix, state what you'll add and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine design choice with meaningful tradeoffs.
|
||||
* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a gap with an "obvious fix" is still a gap and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the fix is genuinely trivial AND there are no meaningful design alternatives. When in doubt, ask.
|
||||
* **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
@@ -345,7 +345,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for
|
||||
* Present 2-3 options. For each: effort to specify now, risk if deferred.
|
||||
* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an obvious fix, state what you'll add and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine design choice with meaningful tradeoffs.
|
||||
* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a gap with an "obvious fix" is still a gap and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the fix is genuinely trivial AND there are no meaningful design alternatives. When in doubt, ask.
|
||||
* **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
+134
-16
@@ -357,6 +357,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -569,20 +698,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
@@ -1891,8 +2006,11 @@ DX reviews:
|
||||
* **Map to DX First Principles above.** One sentence connecting your recommendation
|
||||
to a specific principle (e.g., "This violates 'zero friction at T0' because
|
||||
[persona] needs 3 extra config steps before their first API call").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an
|
||||
obvious fix, state what you'll add and move on, don't waste a question.
|
||||
* **Escape hatch (tightened):** If a section has zero findings, state "No issues,
|
||||
moving on" and proceed. If it has findings, use AskUserQuestion for each — a
|
||||
gap with an "obvious fix" is still a gap and still needs user approval before
|
||||
any change lands in the plan. Only skip AskUserQuestion when the fix is
|
||||
genuinely trivial AND there are no meaningful DX alternatives. When in doubt, ask.
|
||||
* Assume the user hasn't looked at this window in 20 minutes. Re-ground every question.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
@@ -666,8 +666,11 @@ DX reviews:
|
||||
* **Map to DX First Principles above.** One sentence connecting your recommendation
|
||||
to a specific principle (e.g., "This violates 'zero friction at T0' because
|
||||
[persona] needs 3 extra config steps before their first API call").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an
|
||||
obvious fix, state what you'll add and move on, don't waste a question.
|
||||
* **Escape hatch (tightened):** If a section has zero findings, state "No issues,
|
||||
moving on" and proceed. If it has findings, use AskUserQuestion for each — a
|
||||
gap with an "obvious fix" is still a gap and still needs user approval before
|
||||
any change lands in the plan. Only skip AskUserQuestion when the fix is
|
||||
genuinely trivial AND there are no meaningful DX alternatives. When in doubt, ask.
|
||||
* Assume the user hasn't looked at this window in 20 minutes. Re-ground every question.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
+130
-15
@@ -355,6 +355,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -567,20 +696,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
@@ -1506,7 +1621,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for
|
||||
* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Coverage vs kind:** for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include `Completeness: N/10` on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: `Note: options differ in kind, not coverage — no completeness score.` Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score.
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs.
|
||||
* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask.
|
||||
|
||||
## Required outputs
|
||||
|
||||
|
||||
@@ -186,7 +186,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for
|
||||
* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Coverage vs kind:** for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include `Completeness: N/10` on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: `Note: options differ in kind, not coverage — no completeness score.` Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score.
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs.
|
||||
* **Escape hatch (tightened):** If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask.
|
||||
|
||||
## Required outputs
|
||||
|
||||
|
||||
+129
-14
@@ -363,6 +363,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -575,20 +704,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -351,6 +351,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -563,20 +692,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -357,6 +357,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -569,20 +698,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -350,6 +350,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -562,20 +691,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -354,6 +354,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -566,20 +695,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
@@ -87,12 +87,16 @@ export function generatePreamble(ctx: TemplateContext): string {
|
||||
generateVendoringDeprecation(ctx),
|
||||
generateSpawnedSessionCheck(),
|
||||
generateBrainHealthInstruction(ctx),
|
||||
// AskUserQuestion Format renders BEFORE the model overlay so the pacing rule
|
||||
// is the ambient default; the overlay's behavioral nudges land as subordinate
|
||||
// patches. Opus 4.7 reads top-to-bottom and absorbs the first pacing directive
|
||||
// it hits; reversing this order regresses plan-review cadence (v1.6.4.0 bug).
|
||||
...(tier >= 2 ? [generateAskUserFormat(ctx)] : []),
|
||||
generateBrainSyncBlock(ctx),
|
||||
generateModelOverlay(ctx),
|
||||
generateVoiceDirective(tier),
|
||||
...(tier >= 2 ? [
|
||||
generateContextRecovery(ctx),
|
||||
generateAskUserFormat(ctx),
|
||||
generateWritingStyle(ctx),
|
||||
generateCompletenessSection(),
|
||||
generateConfusionProtocol(),
|
||||
|
||||
@@ -3,16 +3,130 @@ import type { TemplateContext } from '../types';
|
||||
export function generateAskUserFormat(_ctx: TemplateContext): string {
|
||||
return `## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the \`_BRANCH\` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with \`RECOMMENDATION: Choose [X] because [one-line reason]\` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with \`Completeness: N/10\` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip \`Completeness: N/10\` entirely and write one line: \`Note: options differ in kind, not coverage — no completeness score.\` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: \`A) ... B) ... C) ...\` — when an option involves effort, show both scales: \`(human: ~X / CC: ~Y)\`
|
||||
### Required shape
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.`;
|
||||
\`\`\`
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
\`\`\`
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is \`D1\`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., \`/plan-ceo-review\` running \`/office-hours\` inline) starts its own
|
||||
D1; label as \`D1 (office-hours)\` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
\`_BRANCH\` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** \`Recommendation: <choice> because <one-line
|
||||
reason>\` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The \`(recommended)\` label on the
|
||||
option is REQUIRED — \`scripts/resolvers/question-tuning.ts\` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each \`Completeness: N/10\` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
\`Note: options differ in kind, not coverage — no completeness score.\`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** \`✅ Simple\` is not a pro. \`✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser\` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet \`✅ No cons — this is a
|
||||
hard-stop choice\` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: \`Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way\`. The \`(recommended)\` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
\`— this is a taste call\` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: \`(human: ~2 days / CC: ~15 min)\`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled \`Question:\` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the \`options\` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.`;
|
||||
}
|
||||
|
||||
|
||||
+129
-14
@@ -353,6 +353,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -565,20 +694,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+129
-14
@@ -355,6 +355,135 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
@@ -567,20 +696,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+228
-14
@@ -355,6 +355,234 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
# gbrain-sync: drain pending writes, pull once per day. Silent no-op when
|
||||
# the feature isn't initialized or gbrain_sync_mode is "off". See
|
||||
# docs/gbrain-sync.md.
|
||||
|
||||
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
|
||||
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
|
||||
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
|
||||
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
|
||||
|
||||
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
|
||||
|
||||
# New-machine hint: URL file present, local .git missing, sync not yet enabled.
|
||||
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
|
||||
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
|
||||
if [ -n "$_BRAIN_NEW_URL" ]; then
|
||||
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
|
||||
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Active-sync path.
|
||||
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
|
||||
# Once-per-day pull.
|
||||
_BRAIN_LAST_PULL_FILE="$_GSTACK_HOME/.brain-last-pull"
|
||||
_BRAIN_NOW=$(date +%s)
|
||||
_BRAIN_DO_PULL=1
|
||||
if [ -f "$_BRAIN_LAST_PULL_FILE" ]; then
|
||||
_BRAIN_LAST=$(cat "$_BRAIN_LAST_PULL_FILE" 2>/dev/null || echo 0)
|
||||
_BRAIN_AGE=$(( _BRAIN_NOW - _BRAIN_LAST ))
|
||||
[ "$_BRAIN_AGE" -lt 86400 ] && _BRAIN_DO_PULL=0
|
||||
fi
|
||||
if [ "$_BRAIN_DO_PULL" = "1" ]; then
|
||||
( cd "$_GSTACK_HOME" && git fetch origin >/dev/null 2>&1 && git merge --ff-only "origin/$(git rev-parse --abbrev-ref HEAD)" >/dev/null 2>&1 ) || true
|
||||
echo "$_BRAIN_NOW" > "$_BRAIN_LAST_PULL_FILE"
|
||||
fi
|
||||
# Drain pending queue, push.
|
||||
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
|
||||
fi
|
||||
|
||||
# Status line — always emitted, easy to grep.
|
||||
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
|
||||
_BRAIN_QUEUE_DEPTH=0
|
||||
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
|
||||
_BRAIN_LAST_PUSH="never"
|
||||
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
|
||||
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
|
||||
else
|
||||
echo "BRAIN_SYNC: off"
|
||||
fi
|
||||
```
|
||||
|
||||
|
||||
|
||||
**Privacy stop-gate (fires ONCE per machine).**
|
||||
|
||||
If the bash output shows `BRAIN_SYNC: off` AND the config value
|
||||
`gbrain_sync_mode_prompted` is `false` AND gbrain is detected on this host
|
||||
(either `gbrain doctor --fast --json` succeeds or the `gbrain` binary is in PATH),
|
||||
fire a one-time privacy gate via AskUserQuestion:
|
||||
|
||||
> gstack can publish your session memory (learnings, plans, designs, retros) to a
|
||||
> private GitHub repo that GBrain indexes across your machines. Higher tiers
|
||||
> include behavioral data (session timelines, developer profile). How much do you
|
||||
> want to sync?
|
||||
|
||||
Options:
|
||||
- A) Everything allowlisted (recommended — maximum cross-machine memory)
|
||||
- B) Only artifacts (plans, designs, retros, learnings) — skip timelines and profile
|
||||
- C) Decline — keep everything local
|
||||
|
||||
After the user answers, run (substituting the chosen value):
|
||||
|
||||
```bash
|
||||
# Chosen mode: full | artifacts-only | off
|
||||
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
|
||||
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
|
||||
```
|
||||
|
||||
If A or B was chosen AND `~/.gstack/.git` doesn't exist, ask a follow-up:
|
||||
"Set up the GBrain sync repo now? (runs `gstack-brain-init`)"
|
||||
- A) Yes, run it now
|
||||
- B) Show me the command, I'll run it myself
|
||||
|
||||
Do not block the skill. Emit the question, continue the skill workflow. The
|
||||
next skill run picks up wherever this left off.
|
||||
|
||||
**At skill END (before the telemetry block),** run these bash commands to
|
||||
catch artifact writes (design docs, plans, retros) that skipped the writer
|
||||
shims, plus drain any still-pending queue entries:
|
||||
|
||||
```bash
|
||||
"~/.claude/skills/gstack/bin/gstack-brain-sync" --discover-new 2>/dev/null || true
|
||||
"~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true
|
||||
```
|
||||
|
||||
|
||||
## Model-Specific Behavioral Patch (claude)
|
||||
|
||||
The following nudges are tuned for the claude model family. They are
|
||||
@@ -468,20 +696,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+228
-14
@@ -344,6 +344,234 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
# gbrain-sync: drain pending writes, pull once per day. Silent no-op when
|
||||
# the feature isn't initialized or gbrain_sync_mode is "off". See
|
||||
# docs/gbrain-sync.md.
|
||||
|
||||
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
|
||||
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
|
||||
_BRAIN_SYNC_BIN="$GSTACK_BIN/gstack-brain-sync"
|
||||
_BRAIN_CONFIG_BIN="$GSTACK_BIN/gstack-config"
|
||||
|
||||
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
|
||||
|
||||
# New-machine hint: URL file present, local .git missing, sync not yet enabled.
|
||||
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
|
||||
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
|
||||
if [ -n "$_BRAIN_NEW_URL" ]; then
|
||||
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
|
||||
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Active-sync path.
|
||||
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
|
||||
# Once-per-day pull.
|
||||
_BRAIN_LAST_PULL_FILE="$_GSTACK_HOME/.brain-last-pull"
|
||||
_BRAIN_NOW=$(date +%s)
|
||||
_BRAIN_DO_PULL=1
|
||||
if [ -f "$_BRAIN_LAST_PULL_FILE" ]; then
|
||||
_BRAIN_LAST=$(cat "$_BRAIN_LAST_PULL_FILE" 2>/dev/null || echo 0)
|
||||
_BRAIN_AGE=$(( _BRAIN_NOW - _BRAIN_LAST ))
|
||||
[ "$_BRAIN_AGE" -lt 86400 ] && _BRAIN_DO_PULL=0
|
||||
fi
|
||||
if [ "$_BRAIN_DO_PULL" = "1" ]; then
|
||||
( cd "$_GSTACK_HOME" && git fetch origin >/dev/null 2>&1 && git merge --ff-only "origin/$(git rev-parse --abbrev-ref HEAD)" >/dev/null 2>&1 ) || true
|
||||
echo "$_BRAIN_NOW" > "$_BRAIN_LAST_PULL_FILE"
|
||||
fi
|
||||
# Drain pending queue, push.
|
||||
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
|
||||
fi
|
||||
|
||||
# Status line — always emitted, easy to grep.
|
||||
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
|
||||
_BRAIN_QUEUE_DEPTH=0
|
||||
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
|
||||
_BRAIN_LAST_PUSH="never"
|
||||
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
|
||||
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
|
||||
else
|
||||
echo "BRAIN_SYNC: off"
|
||||
fi
|
||||
```
|
||||
|
||||
|
||||
|
||||
**Privacy stop-gate (fires ONCE per machine).**
|
||||
|
||||
If the bash output shows `BRAIN_SYNC: off` AND the config value
|
||||
`gbrain_sync_mode_prompted` is `false` AND gbrain is detected on this host
|
||||
(either `gbrain doctor --fast --json` succeeds or the `gbrain` binary is in PATH),
|
||||
fire a one-time privacy gate via AskUserQuestion:
|
||||
|
||||
> gstack can publish your session memory (learnings, plans, designs, retros) to a
|
||||
> private GitHub repo that GBrain indexes across your machines. Higher tiers
|
||||
> include behavioral data (session timelines, developer profile). How much do you
|
||||
> want to sync?
|
||||
|
||||
Options:
|
||||
- A) Everything allowlisted (recommended — maximum cross-machine memory)
|
||||
- B) Only artifacts (plans, designs, retros, learnings) — skip timelines and profile
|
||||
- C) Decline — keep everything local
|
||||
|
||||
After the user answers, run (substituting the chosen value):
|
||||
|
||||
```bash
|
||||
# Chosen mode: full | artifacts-only | off
|
||||
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
|
||||
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
|
||||
```
|
||||
|
||||
If A or B was chosen AND `~/.gstack/.git` doesn't exist, ask a follow-up:
|
||||
"Set up the GBrain sync repo now? (runs `gstack-brain-init`)"
|
||||
- A) Yes, run it now
|
||||
- B) Show me the command, I'll run it myself
|
||||
|
||||
Do not block the skill. Emit the question, continue the skill workflow. The
|
||||
next skill run picks up wherever this left off.
|
||||
|
||||
**At skill END (before the telemetry block),** run these bash commands to
|
||||
catch artifact writes (design docs, plans, retros) that skipped the writer
|
||||
shims, plus drain any still-pending queue entries:
|
||||
|
||||
```bash
|
||||
"$GSTACK_BIN/gstack-brain-sync" --discover-new 2>/dev/null || true
|
||||
"$GSTACK_BIN/gstack-brain-sync" --once 2>/dev/null || true
|
||||
```
|
||||
|
||||
|
||||
## Model-Specific Behavioral Patch (claude)
|
||||
|
||||
The following nudges are tuned for the claude model family. They are
|
||||
@@ -457,20 +685,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
+228
-14
@@ -346,6 +346,234 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. Every element is non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
### Required shape
|
||||
|
||||
Every AskUserQuestion reads like a decision brief, not a bullet list:
|
||||
|
||||
```
|
||||
D<N> — <one-line question title>
|
||||
|
||||
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
|
||||
|
||||
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
|
||||
|
||||
Recommendation: <choice> because <one-line reason>
|
||||
|
||||
Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score)
|
||||
|
||||
Pros / cons:
|
||||
|
||||
A) <option label> (recommended)
|
||||
✅ <pro — concrete, observable, ≥40 chars>
|
||||
✅ <pro>
|
||||
❌ <con — honest, ≥40 chars>
|
||||
|
||||
B) <option label>
|
||||
✅ <pro>
|
||||
❌ <con>
|
||||
|
||||
Net: <one-line synthesis of what you're actually trading off>
|
||||
```
|
||||
|
||||
### Element rules
|
||||
|
||||
1. **D-numbering.** First question in a skill invocation is `D1`. Increment per
|
||||
question within the same skill. This is a model-level instruction, not a
|
||||
runtime counter — you count your own questions. Nested skill invocation
|
||||
(e.g., `/plan-ceo-review` running `/office-hours` inline) starts its own
|
||||
D1; label as `D1 (office-hours)` to disambiguate when the user will see
|
||||
both. Drift is expected over long sessions; minor inconsistency is fine.
|
||||
|
||||
2. **Re-ground.** Before ELI10, state the project, current branch (use the
|
||||
`_BRANCH` value from the preamble, NOT conversation history or gitStatus),
|
||||
and the current plan/task. 1-2 sentences. Assume the user hasn't looked at
|
||||
this window in 20 minutes.
|
||||
|
||||
3. **ELI10 (ALWAYS).** Explain in plain English a smart 16-year-old could
|
||||
follow. Concrete examples and analogies, not function names. Say what it
|
||||
DOES, not what it's called. This is not preamble — the user is about to
|
||||
make a decision and needs context. Even in terse mode, emit the ELI10.
|
||||
|
||||
4. **Stakes if we pick wrong (ALWAYS).** One sentence naming what breaks in
|
||||
concrete terms (pain avoided / capability unlocked / consequence named).
|
||||
"Users see a 3-second spinner" beats "performance may degrade." Forces
|
||||
the trade-off to be real.
|
||||
|
||||
5. **Recommendation (ALWAYS).** `Recommendation: <choice> because <one-line
|
||||
reason>` on its own line. Never omit it. Required for every AskUserQuestion,
|
||||
even when neutral-posture (see rule 8). The `(recommended)` label on the
|
||||
option is REQUIRED — `scripts/resolvers/question-tuning.ts` reads it to
|
||||
power the AUTO_DECIDE path. Omitting it breaks auto-decide.
|
||||
|
||||
6. **Completeness scoring (when meaningful).** When options differ in
|
||||
coverage (full test coverage vs happy path vs shortcut, complete error
|
||||
handling vs partial), score each `Completeness: N/10` on its own line.
|
||||
Calibration: 10 = complete, 7 = happy path only, 3 = shortcut. Flag any
|
||||
option ≤5 where a higher-completeness option exists. When options differ
|
||||
in kind (review posture, architectural A-vs-B, cherry-pick Add/Defer/Skip,
|
||||
two different kinds of systems), SKIP the score and write one line:
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
Do NOT fabricate filler scores — empty 10/10 on every option is worse
|
||||
than no score.
|
||||
|
||||
7. **Pros / cons block.** Every option gets per-bullet ✅ (pro) and ❌ (con)
|
||||
markers. Rules:
|
||||
- **Minimum 2 pros and 1 con per option.** If you can't name a con for
|
||||
the recommended option, the recommendation is hollow — go find one. If
|
||||
you can't name a pro for the rejected option, the question isn't real.
|
||||
- **Minimum 40 characters per bullet.** `✅ Simple` is not a pro. `✅
|
||||
Reuses the YAML frontmatter format already in MEMORY.md, zero new
|
||||
parser` is a pro. Concrete, observable, specific.
|
||||
- **Hard-stop escape** for genuinely one-sided choices (destructive-action
|
||||
confirmation, one-way doors): a single bullet `✅ No cons — this is a
|
||||
hard-stop choice` satisfies the rule. Use sparingly; overuse flips a
|
||||
decision brief into theater.
|
||||
|
||||
8. **Net line (ALWAYS).** Closes the decision with a one-sentence synthesis
|
||||
of what the user is actually trading off. From the reference screenshot:
|
||||
*"The new-format case is speculative. The copy-format case is immediate
|
||||
leverage. Copy now, evolve later if a real pattern emerges."* Not a
|
||||
summary — a verdict frame.
|
||||
|
||||
9. **Neutral-posture handling.** When the skill explicitly says "neutral
|
||||
recommendation posture" (SELECTIVE EXPANSION cherry-picks, taste calls,
|
||||
kind-differentiated choices where neither side dominates), the
|
||||
Recommendation line reads: `Recommendation: <default-choice> — this is a
|
||||
taste call, no strong preference either way`. The `(recommended)` label
|
||||
STAYS on the default option (machine-readable hint for AUTO_DECIDE). The
|
||||
`— this is a taste call` prose is the human-readable neutrality signal.
|
||||
Both coexist.
|
||||
|
||||
10. **Effort both-scales.** When an option involves effort, show both human
|
||||
and CC scales: `(human: ~2 days / CC: ~15 min)`.
|
||||
|
||||
11. **Tool_use, not prose.** A markdown block labeled `Question:` is not a
|
||||
question — the user never sees it as interactive. If you wrote one in
|
||||
prose, stop and reissue as an actual AskUserQuestion tool_use. The rich
|
||||
markdown goes in the question body; the `options` array stays short
|
||||
labels (A, B, C).
|
||||
|
||||
### Self-check before emitting
|
||||
|
||||
Before calling AskUserQuestion, verify:
|
||||
- [ ] D<N> header present
|
||||
- [ ] ELI10 paragraph present (stakes line too)
|
||||
- [ ] Recommendation line present with concrete reason
|
||||
- [ ] Completeness scored (coverage) OR kind-note present (kind)
|
||||
- [ ] Every option has ≥2 ✅ and ≥1 ❌, each ≥40 chars (or hard-stop escape)
|
||||
- [ ] (recommended) label on one option (even for neutral-posture — see rule 9)
|
||||
- [ ] Net line closes the decision
|
||||
- [ ] You are calling the tool, not writing prose
|
||||
|
||||
If you'd need to read the source to understand your own explanation, it's
|
||||
too complex — simplify before emitting.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this
|
||||
baseline.
|
||||
|
||||
## GBrain Sync (skill start)
|
||||
|
||||
```bash
|
||||
# gbrain-sync: drain pending writes, pull once per day. Silent no-op when
|
||||
# the feature isn't initialized or gbrain_sync_mode is "off". See
|
||||
# docs/gbrain-sync.md.
|
||||
|
||||
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
|
||||
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
|
||||
_BRAIN_SYNC_BIN="$GSTACK_BIN/gstack-brain-sync"
|
||||
_BRAIN_CONFIG_BIN="$GSTACK_BIN/gstack-config"
|
||||
|
||||
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
|
||||
|
||||
# New-machine hint: URL file present, local .git missing, sync not yet enabled.
|
||||
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
|
||||
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
|
||||
if [ -n "$_BRAIN_NEW_URL" ]; then
|
||||
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
|
||||
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Active-sync path.
|
||||
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
|
||||
# Once-per-day pull.
|
||||
_BRAIN_LAST_PULL_FILE="$_GSTACK_HOME/.brain-last-pull"
|
||||
_BRAIN_NOW=$(date +%s)
|
||||
_BRAIN_DO_PULL=1
|
||||
if [ -f "$_BRAIN_LAST_PULL_FILE" ]; then
|
||||
_BRAIN_LAST=$(cat "$_BRAIN_LAST_PULL_FILE" 2>/dev/null || echo 0)
|
||||
_BRAIN_AGE=$(( _BRAIN_NOW - _BRAIN_LAST ))
|
||||
[ "$_BRAIN_AGE" -lt 86400 ] && _BRAIN_DO_PULL=0
|
||||
fi
|
||||
if [ "$_BRAIN_DO_PULL" = "1" ]; then
|
||||
( cd "$_GSTACK_HOME" && git fetch origin >/dev/null 2>&1 && git merge --ff-only "origin/$(git rev-parse --abbrev-ref HEAD)" >/dev/null 2>&1 ) || true
|
||||
echo "$_BRAIN_NOW" > "$_BRAIN_LAST_PULL_FILE"
|
||||
fi
|
||||
# Drain pending queue, push.
|
||||
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
|
||||
fi
|
||||
|
||||
# Status line — always emitted, easy to grep.
|
||||
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
|
||||
_BRAIN_QUEUE_DEPTH=0
|
||||
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
|
||||
_BRAIN_LAST_PUSH="never"
|
||||
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
|
||||
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
|
||||
else
|
||||
echo "BRAIN_SYNC: off"
|
||||
fi
|
||||
```
|
||||
|
||||
|
||||
|
||||
**Privacy stop-gate (fires ONCE per machine).**
|
||||
|
||||
If the bash output shows `BRAIN_SYNC: off` AND the config value
|
||||
`gbrain_sync_mode_prompted` is `false` AND gbrain is detected on this host
|
||||
(either `gbrain doctor --fast --json` succeeds or the `gbrain` binary is in PATH),
|
||||
fire a one-time privacy gate via AskUserQuestion:
|
||||
|
||||
> gstack can publish your session memory (learnings, plans, designs, retros) to a
|
||||
> private GitHub repo that GBrain indexes across your machines. Higher tiers
|
||||
> include behavioral data (session timelines, developer profile). How much do you
|
||||
> want to sync?
|
||||
|
||||
Options:
|
||||
- A) Everything allowlisted (recommended — maximum cross-machine memory)
|
||||
- B) Only artifacts (plans, designs, retros, learnings) — skip timelines and profile
|
||||
- C) Decline — keep everything local
|
||||
|
||||
After the user answers, run (substituting the chosen value):
|
||||
|
||||
```bash
|
||||
# Chosen mode: full | artifacts-only | off
|
||||
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
|
||||
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
|
||||
```
|
||||
|
||||
If A or B was chosen AND `~/.gstack/.git` doesn't exist, ask a follow-up:
|
||||
"Set up the GBrain sync repo now? (runs `gstack-brain-init`)"
|
||||
- A) Yes, run it now
|
||||
- B) Show me the command, I'll run it myself
|
||||
|
||||
Do not block the skill. Emit the question, continue the skill workflow. The
|
||||
next skill run picks up wherever this left off.
|
||||
|
||||
**At skill END (before the telemetry block),** run these bash commands to
|
||||
catch artifact writes (design docs, plans, retros) that skipped the writer
|
||||
shims, plus drain any still-pending queue entries:
|
||||
|
||||
```bash
|
||||
"$GSTACK_BIN/gstack-brain-sync" --discover-new 2>/dev/null || true
|
||||
"$GSTACK_BIN/gstack-brain-sync" --once 2>/dev/null || true
|
||||
```
|
||||
|
||||
|
||||
## Model-Specific Behavioral Patch (claude)
|
||||
|
||||
The following nudges are tuned for the claude model family. They are
|
||||
@@ -459,20 +687,6 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call. All four elements are non-skippable. If you find yourself about to skip any of them, stop and back up.**
|
||||
|
||||
1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
|
||||
2. **Simplify (ELI10, ALWAYS):** Explain what's happening in plain English a smart 16-year-old could follow. Concrete examples and analogies, not function names or internal jargon. Say what it DOES, not what it's called. State the stakes: what breaks if we pick wrong. This is NOT optional verbosity and it is NOT preamble — the user is about to make a decision and needs context. Even if you'd normally stay terse, emit the ELI10 paragraph. The user will ask for it anyway; do it the first time.
|
||||
3. **Recommend (ALWAYS):** Every question ends with `RECOMMENDATION: Choose [X] because [one-line reason]` on its own line. Never omit it. Never collapse it into the options list. Required for every AskUserQuestion, regardless of whether the options are coverage-differentiated or different-in-kind.
|
||||
4. **Score completeness (when meaningful):** When options differ in coverage (e.g. full test coverage vs happy path vs shortcut, complete error handling vs partial), score each with `Completeness: N/10` on its own line. Calibration: 10 = complete (all edge cases, full coverage), 7 = happy path only, 3 = shortcut. Flag any option ≤5 where a higher-completeness option exists. When options differ in kind (picking a review posture, picking an architectural approach, cherry-pick Add/Defer/Skip, choosing between two different kinds of systems), the completeness axis doesn't apply — skip `Completeness: N/10` entirely and write one line: `Note: options differ in kind, not coverage — no completeness score.` Do not fabricate filler scores.
|
||||
5. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
|
||||
|
||||
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
|
||||
|
||||
Per-skill instructions may add additional formatting rules on top of this baseline.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*.
|
||||
|
||||
@@ -241,10 +241,11 @@ describe('gen-skill-docs', () => {
|
||||
expect(content).toContain('git branch --show-current');
|
||||
});
|
||||
|
||||
test('tier 2+ skills contain ELI16 simplification rules (AskUserQuestion format)', () => {
|
||||
test('tier 2+ skills contain ELI10 simplification rules (AskUserQuestion format)', () => {
|
||||
// Root SKILL.md is tier 1 (no AskUserQuestion format). Check a tier 2+ skill instead.
|
||||
// v1.7.0.0 Pros/Cons format uses "ELI10 (ALWAYS)" rather than "Simplify (ELI10".
|
||||
const content = fs.readFileSync(path.join(ROOT, 'cso', 'SKILL.md'), 'utf-8');
|
||||
expect(content).toContain('Simplify (ELI10');
|
||||
expect(content).toContain('ELI10');
|
||||
expect(content).toContain('plain English');
|
||||
expect(content).toContain('not function names');
|
||||
});
|
||||
|
||||
@@ -84,10 +84,27 @@ export const E2E_TOUCHFILES: Record<string, string[]> = {
|
||||
|
||||
// AskUserQuestion format regression (RECOMMENDATION + Completeness: N/10)
|
||||
// Fires when either template OR the two preamble resolvers change.
|
||||
'plan-ceo-review-format-mode': ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts'],
|
||||
'plan-ceo-review-format-approach': ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts'],
|
||||
'plan-eng-review-format-coverage': ['plan-eng-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts'],
|
||||
'plan-eng-review-format-kind': ['plan-eng-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts'],
|
||||
'plan-ceo-review-format-mode': ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'plan-ceo-review-format-approach': ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'plan-eng-review-format-coverage': ['plan-eng-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'plan-eng-review-format-kind': ['plan-eng-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
|
||||
// v1.7.0.0 Pros/Cons format cadence + format + negative-escape evals.
|
||||
// Dependencies: same as format-mode + the 4 plan-review templates + overlay.
|
||||
// All periodic-tier (non-deterministic Opus 4.7 behavior).
|
||||
'plan-ceo-review-prosons-cadence': ['plan-ceo-review/**', 'plan-eng-review/**', 'plan-design-review/**', 'plan-devex-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'plan-review-prosons-format': ['plan-ceo-review/**', 'plan-eng-review/**', 'plan-design-review/**', 'plan-devex-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'plan-review-prosons-hardstop-neg': ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'plan-review-prosons-neutral-neg': ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
|
||||
// Expanded coverage (CT3) — 6 non-plan-review skills inherit Pros/Cons via preamble
|
||||
'ship-prosons-format': ['ship/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'office-hours-prosons-format': ['office-hours/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'investigate-prosons-format': ['investigate/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'qa-prosons-format': ['qa/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'review-prosons-format': ['review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'design-review-prosons-format': ['design-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
'document-release-prosons-format': ['document-release/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'model-overlays/opus-4-7.md'],
|
||||
|
||||
// /plan-tune (v1 observational)
|
||||
'plan-tune-inspect': ['plan-tune/**', 'scripts/question-registry.ts', 'scripts/psychographic-signals.ts', 'scripts/one-way-doors.ts', 'bin/gstack-question-log', 'bin/gstack-question-preference', 'bin/gstack-developer-profile'],
|
||||
@@ -288,6 +305,21 @@ export const E2E_TIERS: Record<string, 'gate' | 'periodic'> = {
|
||||
'plan-eng-review-format-coverage': 'periodic',
|
||||
'plan-eng-review-format-kind': 'periodic',
|
||||
|
||||
// v1.7.0.0 Pros/Cons format — cadence + negative-escape evals (all periodic)
|
||||
'plan-ceo-review-prosons-cadence': 'periodic',
|
||||
'plan-review-prosons-format': 'periodic',
|
||||
'plan-review-prosons-hardstop-neg': 'periodic',
|
||||
'plan-review-prosons-neutral-neg': 'periodic',
|
||||
|
||||
// CT3 expanded coverage — non-plan-review skills inheriting Pros/Cons (all periodic)
|
||||
'ship-prosons-format': 'periodic',
|
||||
'office-hours-prosons-format': 'periodic',
|
||||
'investigate-prosons-format': 'periodic',
|
||||
'qa-prosons-format': 'periodic',
|
||||
'review-prosons-format': 'periodic',
|
||||
'design-review-prosons-format': 'periodic',
|
||||
'document-release-prosons-format': 'periodic',
|
||||
|
||||
// /plan-tune — gate (core v1 DX promise: plain-English intent routing)
|
||||
'plan-tune-inspect': 'gate',
|
||||
|
||||
|
||||
@@ -0,0 +1,98 @@
|
||||
/**
|
||||
* Opus 4.7 model overlay — gate-tier assertions on the pacing directive.
|
||||
*
|
||||
* v1.6.4.0 regressed plan-review cadence because the Opus 4.7 overlay
|
||||
* carried a "Batch your questions" directive that physically rendered
|
||||
* above the skill-level pacing rule. Opus 4.7 read top-to-bottom,
|
||||
* absorbed batching as the ambient default, and stopped honoring the
|
||||
* plan-review STOP directives.
|
||||
*
|
||||
* v1.7.0.0 replaces that block with "Pace questions to the skill" —
|
||||
* one-question-at-a-time is now the default when the skill contains
|
||||
* STOP directives; batching becomes the explicit exception.
|
||||
*
|
||||
* This test asserts:
|
||||
* - The new "Pace questions" directive is present
|
||||
* - The old "Batch your questions" directive is gone
|
||||
* - The AUTO_DECIDE-compatible language survives (subordination, skill wins)
|
||||
*/
|
||||
import { describe, test, expect } from 'bun:test';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import type { TemplateContext } from '../scripts/resolvers/types';
|
||||
import { HOST_PATHS } from '../scripts/resolvers/types';
|
||||
import { generateModelOverlay } from '../scripts/resolvers/model-overlay';
|
||||
|
||||
function makeCtx(model: string): TemplateContext {
|
||||
return {
|
||||
skillName: 'test-skill',
|
||||
tmplPath: 'test.tmpl',
|
||||
host: 'claude',
|
||||
paths: HOST_PATHS.claude,
|
||||
preambleTier: 2,
|
||||
model,
|
||||
};
|
||||
}
|
||||
|
||||
const ROOT = path.resolve(__dirname, '..');
|
||||
|
||||
describe('Opus 4.7 overlay — pacing directive', () => {
|
||||
test('raw opus-4-7.md contains "Pace questions to the skill"', () => {
|
||||
const raw = fs.readFileSync(
|
||||
path.join(ROOT, 'model-overlays/opus-4-7.md'),
|
||||
'utf-8',
|
||||
);
|
||||
expect(raw).toContain('Pace questions to the skill');
|
||||
});
|
||||
|
||||
test('raw opus-4-7.md does NOT contain "Batch your questions" directive', () => {
|
||||
const raw = fs.readFileSync(
|
||||
path.join(ROOT, 'model-overlays/opus-4-7.md'),
|
||||
'utf-8',
|
||||
);
|
||||
expect(raw).not.toContain('**Batch your questions.**');
|
||||
});
|
||||
|
||||
test('resolved overlay output contains "Pace questions to the skill"', () => {
|
||||
const out = generateModelOverlay(makeCtx('opus-4-7'));
|
||||
expect(out).toContain('Pace questions to the skill');
|
||||
});
|
||||
|
||||
test('resolved overlay inherits from claude base (INHERIT:claude)', () => {
|
||||
const out = generateModelOverlay(makeCtx('opus-4-7'));
|
||||
// The claude base contributes the subordination wrapper + Todo discipline
|
||||
expect(out).toContain('Todo-list discipline');
|
||||
expect(out).toContain('subordinate');
|
||||
});
|
||||
|
||||
test('resolved overlay says skill STOP directives trigger one-per-turn pacing', () => {
|
||||
const out = generateModelOverlay(makeCtx('opus-4-7'));
|
||||
expect(out).toMatch(/STOP\. AskUserQuestion/);
|
||||
expect(out).toMatch(/pace one question per turn|one question per turn/i);
|
||||
});
|
||||
|
||||
test('resolved overlay requires AskUserQuestion as tool_use', () => {
|
||||
const out = generateModelOverlay(makeCtx('opus-4-7'));
|
||||
expect(out).toContain('tool_use');
|
||||
});
|
||||
|
||||
test('resolved overlay flags "obvious fix" findings still need user approval', () => {
|
||||
const out = generateModelOverlay(makeCtx('opus-4-7'));
|
||||
expect(out).toMatch(/obvious fix/i);
|
||||
expect(out).toMatch(/user approval/i);
|
||||
});
|
||||
|
||||
test('resolved overlay keeps Fan out / Effort-match / Literal interpretation nudges', () => {
|
||||
const out = generateModelOverlay(makeCtx('opus-4-7'));
|
||||
expect(out).toContain('Fan out explicitly');
|
||||
expect(out).toContain('Effort-match the step');
|
||||
expect(out).toContain('Literal interpretation awareness');
|
||||
});
|
||||
|
||||
test('claude overlay (no INHERIT chain) does not carry the pacing directive', () => {
|
||||
// Claude is the default overlay; opus-4-7 inherits FROM claude.
|
||||
// The pacing directive belongs to opus-4-7 only.
|
||||
const out = generateModelOverlay(makeCtx('claude'));
|
||||
expect(out).not.toContain('Pace questions to the skill');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,72 @@
|
||||
/**
|
||||
* Preamble composition order — gate-tier test.
|
||||
*
|
||||
* Asserts that the AskUserQuestion Format section renders BEFORE the
|
||||
* Model-Specific Behavioral Patch section in tier-≥2 preamble output.
|
||||
* This order is load-bearing: Opus 4.7 reads top-to-bottom and absorbs
|
||||
* the first pacing directive it hits. v1.6.4.0 regressed plan-review
|
||||
* cadence because the overlay rendered first with "Batch your questions"
|
||||
* as the ambient default.
|
||||
*
|
||||
* If someone later reorders `scripts/resolvers/preamble.ts` so Overlay
|
||||
* comes before Format, this test catches it before the next model
|
||||
* migration can silently re-break the plan-review pacing.
|
||||
*/
|
||||
import { describe, test, expect } from 'bun:test';
|
||||
import type { TemplateContext } from '../scripts/resolvers/types';
|
||||
import { HOST_PATHS } from '../scripts/resolvers/types';
|
||||
import { generatePreamble } from '../scripts/resolvers/preamble';
|
||||
|
||||
function makeCtx(
|
||||
host: 'claude' | 'codex',
|
||||
tier: 1 | 2 | 3 | 4,
|
||||
model?: string,
|
||||
): TemplateContext {
|
||||
return {
|
||||
skillName: 'test-skill',
|
||||
tmplPath: 'test.tmpl',
|
||||
host,
|
||||
paths: HOST_PATHS[host],
|
||||
preambleTier: tier,
|
||||
...(model ? { model } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
describe('Preamble composition order', () => {
|
||||
test('AskUserQuestion Format renders before Model-Specific Behavioral Patch (tier 2, claude)', () => {
|
||||
const out = generatePreamble(makeCtx('claude', 2, 'claude'));
|
||||
const formatIdx = out.indexOf('## AskUserQuestion Format');
|
||||
const overlayIdx = out.indexOf('## Model-Specific Behavioral Patch');
|
||||
expect(formatIdx).toBeGreaterThan(-1);
|
||||
expect(overlayIdx).toBeGreaterThan(-1);
|
||||
expect(formatIdx).toBeLessThan(overlayIdx);
|
||||
});
|
||||
|
||||
test('AskUserQuestion Format renders before Model-Specific Behavioral Patch (tier 2, opus-4-7)', () => {
|
||||
const out = generatePreamble(makeCtx('claude', 2, 'opus-4-7'));
|
||||
const formatIdx = out.indexOf('## AskUserQuestion Format');
|
||||
const overlayIdx = out.indexOf('## Model-Specific Behavioral Patch');
|
||||
expect(formatIdx).toBeGreaterThan(-1);
|
||||
expect(overlayIdx).toBeGreaterThan(-1);
|
||||
expect(formatIdx).toBeLessThan(overlayIdx);
|
||||
});
|
||||
|
||||
test('AskUserQuestion Format renders before Model-Specific Behavioral Patch (tier 3)', () => {
|
||||
const out = generatePreamble(makeCtx('claude', 3, 'opus-4-7'));
|
||||
const formatIdx = out.indexOf('## AskUserQuestion Format');
|
||||
const overlayIdx = out.indexOf('## Model-Specific Behavioral Patch');
|
||||
expect(formatIdx).toBeLessThan(overlayIdx);
|
||||
});
|
||||
|
||||
test('AskUserQuestion Format renders before Model-Specific Behavioral Patch (codex host)', () => {
|
||||
const out = generatePreamble(makeCtx('codex', 2, 'opus-4-7'));
|
||||
const formatIdx = out.indexOf('## AskUserQuestion Format');
|
||||
const overlayIdx = out.indexOf('## Model-Specific Behavioral Patch');
|
||||
expect(formatIdx).toBeLessThan(overlayIdx);
|
||||
});
|
||||
|
||||
test('tier 1 preamble does NOT include AskUserQuestion Format (but MAY include overlay)', () => {
|
||||
const out = generatePreamble(makeCtx('claude', 1));
|
||||
expect(out).not.toContain('## AskUserQuestion Format');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,121 @@
|
||||
/**
|
||||
* AskUserQuestion Format resolver — gate-tier assertions on the generated
|
||||
* Pros/Cons format directive block.
|
||||
*
|
||||
* v1.7.0.0 introduces Pros/Cons decision-brief formatting:
|
||||
* - D<N> numbered header
|
||||
* - ELI10 paragraph
|
||||
* - Stakes-if-we-pick-wrong line
|
||||
* - Recommendation line (mandatory, even for neutral posture)
|
||||
* - Pros/Cons block with ✅/❌ per option, min 2 pros + 1 con, ≥40 char bullets
|
||||
* - Net: synthesis line
|
||||
*
|
||||
* This test pins the format contract so a future edit to the resolver
|
||||
* can't silently drop a rule. If the resolver stops emitting one of
|
||||
* these tokens, bun test catches it in milliseconds instead of waiting
|
||||
* for the weekly periodic eval to notice.
|
||||
*/
|
||||
import { describe, test, expect } from 'bun:test';
|
||||
import type { TemplateContext } from '../scripts/resolvers/types';
|
||||
import { HOST_PATHS } from '../scripts/resolvers/types';
|
||||
import { generateAskUserFormat } from '../scripts/resolvers/preamble/generate-ask-user-format';
|
||||
|
||||
function makeCtx(): TemplateContext {
|
||||
return {
|
||||
skillName: 'test-skill',
|
||||
tmplPath: 'test.tmpl',
|
||||
host: 'claude',
|
||||
paths: HOST_PATHS.claude,
|
||||
preambleTier: 2,
|
||||
};
|
||||
}
|
||||
|
||||
describe('generateAskUserFormat — v1.7.0.0 Pros/Cons format', () => {
|
||||
const out = generateAskUserFormat(makeCtx());
|
||||
|
||||
test('includes AskUserQuestion Format header', () => {
|
||||
expect(out).toContain('## AskUserQuestion Format');
|
||||
});
|
||||
|
||||
test('documents D-numbered header requirement', () => {
|
||||
expect(out).toContain('D<N>');
|
||||
expect(out).toMatch(/first question in a skill invocation is `D1`/i);
|
||||
});
|
||||
|
||||
test('documents ELI10 requirement', () => {
|
||||
expect(out).toContain('ELI10');
|
||||
expect(out).toMatch(/plain English.*16-year-old/);
|
||||
});
|
||||
|
||||
test('documents Stakes-if-we-pick-wrong line', () => {
|
||||
expect(out).toContain('Stakes if we pick wrong');
|
||||
});
|
||||
|
||||
test('documents mandatory Recommendation line', () => {
|
||||
expect(out).toContain('Recommendation: <choice>');
|
||||
expect(out).toMatch(/Recommendation.*ALWAYS|Recommendation \(ALWAYS\)/);
|
||||
});
|
||||
|
||||
test('documents Pros / cons block header', () => {
|
||||
expect(out).toContain('Pros / cons:');
|
||||
});
|
||||
|
||||
test('documents ✅ pro markers with min count + min length rule', () => {
|
||||
expect(out).toContain('✅');
|
||||
expect(out).toMatch(/[Mm]inimum 2 pros/);
|
||||
expect(out).toMatch(/40 characters|≥40 chars/);
|
||||
});
|
||||
|
||||
test('documents ❌ con markers with min count rule', () => {
|
||||
expect(out).toContain('❌');
|
||||
expect(out).toMatch(/1 con per option|minimum.*1 con/i);
|
||||
});
|
||||
|
||||
test('documents hard-stop escape with exact phrase', () => {
|
||||
// "No cons — this is a hard-stop choice" may span a line break in the
|
||||
// rendered resolver text; match across whitespace collapses.
|
||||
expect(out).toMatch(/No cons\s+—\s+this is a\s+hard-stop choice/);
|
||||
});
|
||||
|
||||
test('documents neutral-posture escape preserving (recommended) label', () => {
|
||||
// CT1 resolution: (recommended) label STAYS on default option to preserve
|
||||
// AUTO_DECIDE contract. Neutrality expressed in prose only.
|
||||
expect(out).toMatch(/taste call/i);
|
||||
// `s` flag makes . match newlines — the label + STAYS phrase spans a line break
|
||||
expect(out).toMatch(/\(recommended\)[\s\S]*STAYS|STAYS[\s\S]*\(recommended\)/);
|
||||
expect(out).toMatch(/AUTO_DECIDE/);
|
||||
});
|
||||
|
||||
test('documents Net line for closing synthesis', () => {
|
||||
expect(out).toMatch(/^Net:/m);
|
||||
expect(out).toMatch(/synthesis|tradeoff/i);
|
||||
});
|
||||
|
||||
test('documents Completeness scoring rules (coverage vs kind)', () => {
|
||||
expect(out).toContain('Completeness');
|
||||
expect(out).toMatch(/10 = complete/);
|
||||
expect(out).toMatch(/options differ in kind, not coverage/);
|
||||
});
|
||||
|
||||
test('documents tool_use mandate (rule 11)', () => {
|
||||
expect(out).toMatch(/tool_use/);
|
||||
// "not a question" spans a newline in the rendered text
|
||||
expect(out).toMatch(/not a[\s\S]*question|not[\s\S]*interactive/i);
|
||||
});
|
||||
|
||||
test('includes self-check before emitting', () => {
|
||||
expect(out).toContain('Self-check before emitting');
|
||||
expect(out).toMatch(/D<N> header present/);
|
||||
expect(out).toMatch(/Net line closes/);
|
||||
});
|
||||
|
||||
test('documents D-numbering as model-level not runtime state', () => {
|
||||
// Codex finding #4 caveat: D-numbering is a prompt wish, not a system
|
||||
// guarantee. TemplateContext has no counter. This check pins the caveat.
|
||||
expect(out).toMatch(/model-level instruction|not a runtime counter|count your own/i);
|
||||
});
|
||||
|
||||
test('per-skill override guidance preserved', () => {
|
||||
expect(out).toMatch(/Per-skill instructions may add/);
|
||||
});
|
||||
});
|
||||
@@ -35,10 +35,25 @@ const evalCollector = createEvalCollector('e2e-plan-format');
|
||||
// Regex predicates applied to captured AskUserQuestion content.
|
||||
// RECOMMENDATION regex is lenient on intervening markdown markers (e.g.
|
||||
// agent writes `**RECOMMENDATION:** Choose` — the `**` closers are benign).
|
||||
const RECOMMENDATION_RE = /RECOMMENDATION:[*\s]*Choose/;
|
||||
// Post v1.7.0.0: "Recommendation:" (mixed-case) is the canonical form per
|
||||
// the Pros/Cons format; accept both cases for backward compatibility.
|
||||
const RECOMMENDATION_RE = /[Rr]ecommendation:[*\s]*Choose/;
|
||||
const COMPLETENESS_RE = /Completeness:\s*\d{1,2}\/10/;
|
||||
const KIND_NOTE_RE = /options differ in kind/i;
|
||||
|
||||
// v1.7.0.0 Pros/Cons format tokens. Tests are additive: existing
|
||||
// RECOMMENDATION / Completeness / kind-note assertions still hold; new
|
||||
// format tokens are asserted ONLY when the capture is from a v1.7+
|
||||
// skill rendering. Presence is optional for backward compatibility during
|
||||
// rollout; the periodic-tier cadence+format eval (see skill-e2e-plan-cadence)
|
||||
// is the strict gate for the new format.
|
||||
const PROS_CONS_HEADER_RE = /Pros\s*\/\s*cons:/i;
|
||||
const PRO_BULLET_RE = /^\s*✅\s+\S/m;
|
||||
const CON_BULLET_RE = /^\s*❌\s+\S/m;
|
||||
const NET_LINE_RE = /^Net:\s+\S/m;
|
||||
const D_NUMBER_RE = /^D\d+\s+—/m;
|
||||
const STAKES_RE = /Stakes if we pick wrong:/i;
|
||||
|
||||
const SAMPLE_PLAN = `# Plan: Add User Dashboard
|
||||
|
||||
## Context
|
||||
|
||||
@@ -0,0 +1,352 @@
|
||||
/**
|
||||
* v1.7.0.0 Pros/Cons format regression tests for plan reviews.
|
||||
*
|
||||
* Extends the v1.6.3.0 format harness (skill-e2e-plan-format.test.ts) with
|
||||
* four new cases covering the Pros/Cons decision-brief format:
|
||||
*
|
||||
* 1. Format positive — every AskUserQuestion renders with D<N> / ELI10 /
|
||||
* Stakes / Recommendation / Pros/cons / ✅×2+ / ❌×1+ / Net tokens.
|
||||
* 2. Hard-stop positive — destructive-action question may use the single
|
||||
* "No cons — this is a hard-stop choice" escape.
|
||||
* 3. Hard-stop NEGATIVE (CT2) — plan with genuine tradeoff, model must NOT
|
||||
* dodge to the hard-stop escape. Forces real tradeoff articulation.
|
||||
* 4. Neutral-posture NEGATIVE (CT2) — plan with one clearly-dominant option,
|
||||
* model must emit (recommended) label and concrete recommendation, NOT
|
||||
* "no preference — taste call" dodge.
|
||||
*
|
||||
* Capture pattern matches existing harness: agent writes verbatim
|
||||
* AskUserQuestion text to $OUT_FILE; regex predicates run on the captured
|
||||
* file. Classified periodic (Opus 4.7 non-deterministic).
|
||||
*
|
||||
* FOLLOW-UP (not in v1.7.0.0):
|
||||
* - True cadence eval (3 findings → 3 distinct asks across turns). Current
|
||||
* $OUT_FILE harness captures ONE would-be question per session. Multi-turn
|
||||
* cadence needs new harness support. Filed in TODOs.
|
||||
* - Expanded coverage for /ship /office-hours /investigate /qa /review
|
||||
* /design-review /document-release. Touchfiles entries already exist; eval
|
||||
* cases will land as follow-up PRs per skill.
|
||||
*/
|
||||
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
|
||||
import { runSkillTest } from './helpers/session-runner';
|
||||
import {
|
||||
ROOT, runId,
|
||||
describeIfSelected, testConcurrentIfSelected,
|
||||
logCost, recordE2E,
|
||||
createEvalCollector, finalizeEvalCollector,
|
||||
} from './helpers/e2e-helpers';
|
||||
import { spawnSync } from 'child_process';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import * as os from 'os';
|
||||
|
||||
const evalCollector = createEvalCollector('e2e-plan-prosons');
|
||||
|
||||
// v1.7.0.0 format tokens
|
||||
const D_NUMBER_RE = /D\d+\s+—/;
|
||||
const ELI10_RE = /ELI10:/i;
|
||||
const STAKES_RE = /Stakes if we pick wrong:/i;
|
||||
const RECOMMENDATION_RE = /[Rr]ecommendation:/;
|
||||
const PROS_CONS_HEADER_RE = /Pros\s*\/\s*cons:/i;
|
||||
const NET_LINE_RE = /^Net:/m;
|
||||
const HARD_STOP_ESCAPE_RE = /✅\s+No cons\s+—\s+this is a hard-stop choice/;
|
||||
const NEUTRAL_POSTURE_RE = /taste call/i;
|
||||
const RECOMMENDED_LABEL_RE = /\(recommended\)/;
|
||||
|
||||
function countChars(text: string, char: string): number {
|
||||
return (text.match(new RegExp(char, 'g')) || []).length;
|
||||
}
|
||||
|
||||
const TRADEOFF_PLAN = `# Plan: Add user dashboard caching
|
||||
|
||||
## Context
|
||||
Dashboard renders in 3s on cold load, 800ms on warm cache. Users complain.
|
||||
|
||||
## Approach options
|
||||
|
||||
### Option A: Redis cache layer (complete)
|
||||
- Add Redis with 5min TTL for dashboard aggregates.
|
||||
- Cold path: compute + cache. Warm path: fetch from cache.
|
||||
- Needs Redis infra, cache invalidation logic for activity updates.
|
||||
- Covers all users, all flows, fails gracefully on cache miss.
|
||||
|
||||
### Option B: In-memory LRU cache (happy path only)
|
||||
- Per-process LRU with 100-entry cap.
|
||||
- No cross-process sharing; cache warms per-pod.
|
||||
- Skips cache invalidation; stale reads up to 5min.
|
||||
|
||||
Both options have real pros and cons. This is a genuine tradeoff.
|
||||
`;
|
||||
|
||||
const HARDSTOP_PLAN = `# Plan: Delete all user sessions
|
||||
|
||||
## Context
|
||||
Security incident. All active sessions need to be terminated immediately.
|
||||
|
||||
## Action
|
||||
Run \`DELETE FROM sessions WHERE TRUE\`. No dry-run mode.
|
||||
|
||||
This is a one-way door. There is no "partial" version.
|
||||
`;
|
||||
|
||||
const DOMINANT_PLAN = `# Plan: Add input validation to signup endpoint
|
||||
|
||||
## Context
|
||||
Signup endpoint currently accepts any email string and any password length.
|
||||
Bug report: users type gibberish, signup succeeds, they can't log in.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A: Full RFC 5322 email validation + min 8-char password + server-side checks
|
||||
- Catches malformed emails, rejects weak passwords, validated on server.
|
||||
- Prevents the reported bug and adjacent bugs.
|
||||
- Standard web practice.
|
||||
|
||||
### Option B: Client-side type="email" only, no password validation
|
||||
- Only catches some browsers' built-in validation.
|
||||
- Attackers bypass by disabling JS.
|
||||
- Does not fix the reported bug.
|
||||
|
||||
Option A clearly dominates on coverage. This is NOT a taste call.
|
||||
`;
|
||||
|
||||
function setupPlanDir(tmpPrefix: string, planContent: string, skillName: string): string {
|
||||
const planDir = fs.mkdtempSync(path.join(os.tmpdir(), tmpPrefix));
|
||||
const run = (cmd: string, args: string[]) =>
|
||||
spawnSync(cmd, args, { cwd: planDir, stdio: 'pipe', timeout: 5000 });
|
||||
|
||||
run('git', ['init', '-b', 'main']);
|
||||
run('git', ['config', 'user.email', 'test@test.com']);
|
||||
run('git', ['config', 'user.name', 'Test']);
|
||||
|
||||
fs.writeFileSync(path.join(planDir, 'plan.md'), planContent);
|
||||
run('git', ['add', '.']);
|
||||
run('git', ['commit', '-m', 'add plan']);
|
||||
|
||||
fs.mkdirSync(path.join(planDir, skillName), { recursive: true });
|
||||
fs.copyFileSync(
|
||||
path.join(ROOT, skillName, 'SKILL.md'),
|
||||
path.join(planDir, skillName, 'SKILL.md'),
|
||||
);
|
||||
|
||||
return planDir;
|
||||
}
|
||||
|
||||
function captureInstruction(outFile: string): string {
|
||||
return `Write the verbatim text of the single AskUserQuestion you would have made to ${outFile} (full text including D<N> header, ELI10, Stakes, Recommendation, Pros/cons, and Net line — the complete rich markdown body). Do NOT call any tool to ask the user. Do NOT paraphrase. This is a format-capture test.`;
|
||||
}
|
||||
|
||||
// --- Case 1: Format positive — all v1.7.0.0 tokens present ---
|
||||
|
||||
describeIfSelected('Plan Prosons — Format Positive', ['plan-review-prosons-format'], () => {
|
||||
let planDir: string;
|
||||
let outFile: string;
|
||||
|
||||
beforeAll(() => {
|
||||
planDir = setupPlanDir('skill-e2e-plan-prosons-format-', TRADEOFF_PLAN, 'plan-ceo-review');
|
||||
outFile = path.join(planDir, 'ask-capture.md');
|
||||
});
|
||||
|
||||
afterAll(() => {
|
||||
try { fs.rmSync(planDir, { recursive: true, force: true }); } catch {}
|
||||
});
|
||||
|
||||
testConcurrentIfSelected('plan-review-prosons-format', async () => {
|
||||
const result = await runSkillTest({
|
||||
prompt: `Read plan-ceo-review/SKILL.md for the review workflow.
|
||||
|
||||
Read plan.md — two cache approaches with real tradeoffs. Pick the architectural approach via AskUserQuestion (Step 0C-bis / Implementation Alternatives). These options differ in coverage.
|
||||
|
||||
${captureInstruction(outFile)}
|
||||
|
||||
After writing the file, stop.`,
|
||||
workingDirectory: planDir,
|
||||
maxTurns: 10,
|
||||
timeout: 240_000,
|
||||
testName: 'plan-review-prosons-format',
|
||||
runId,
|
||||
model: 'claude-opus-4-7',
|
||||
});
|
||||
|
||||
logCost('/plan-review prosons format positive', result);
|
||||
recordE2E(evalCollector, '/plan-review-prosons-format', 'Plan Prosons — Format Positive', result, {
|
||||
passed: ['success', 'error_max_turns'].includes(result.exitReason),
|
||||
});
|
||||
expect(['success', 'error_max_turns']).toContain(result.exitReason);
|
||||
|
||||
expect(fs.existsSync(outFile)).toBe(true);
|
||||
const captured = fs.readFileSync(outFile, 'utf-8');
|
||||
expect(captured.length).toBeGreaterThan(200);
|
||||
|
||||
// Every Pros/Cons token present
|
||||
expect(captured).toMatch(D_NUMBER_RE);
|
||||
expect(captured).toMatch(ELI10_RE);
|
||||
expect(captured).toMatch(STAKES_RE);
|
||||
expect(captured).toMatch(RECOMMENDATION_RE);
|
||||
expect(captured).toMatch(PROS_CONS_HEADER_RE);
|
||||
expect(captured).toMatch(NET_LINE_RE);
|
||||
|
||||
// Pro/con bullet counts: ≥2 ✅ and ≥1 ❌ per option (total ≥4 ✅ and ≥2 ❌ for 2 options)
|
||||
expect(countChars(captured, '✅')).toBeGreaterThanOrEqual(4);
|
||||
expect(countChars(captured, '❌')).toBeGreaterThanOrEqual(2);
|
||||
|
||||
// (recommended) label on one option
|
||||
expect(captured).toMatch(RECOMMENDED_LABEL_RE);
|
||||
}, 300_000);
|
||||
});
|
||||
|
||||
// --- Case 2: Hard-stop escape NEGATIVE (CT2) ---
|
||||
|
||||
describeIfSelected('Plan Prosons — Hard-stop Negative', ['plan-review-prosons-hardstop-neg'], () => {
|
||||
let planDir: string;
|
||||
let outFile: string;
|
||||
|
||||
beforeAll(() => {
|
||||
planDir = setupPlanDir('skill-e2e-plan-prosons-hardstop-neg-', TRADEOFF_PLAN, 'plan-ceo-review');
|
||||
outFile = path.join(planDir, 'ask-capture.md');
|
||||
});
|
||||
|
||||
afterAll(() => {
|
||||
try { fs.rmSync(planDir, { recursive: true, force: true }); } catch {}
|
||||
});
|
||||
|
||||
testConcurrentIfSelected('plan-review-prosons-hardstop-neg', async () => {
|
||||
const result = await runSkillTest({
|
||||
prompt: `Read plan-ceo-review/SKILL.md.
|
||||
|
||||
Read plan.md — this has REAL tradeoffs between Redis and in-memory caching (both have pros and cons). Pick the architectural approach via AskUserQuestion.
|
||||
|
||||
${captureInstruction(outFile)}
|
||||
|
||||
After writing the file, stop.`,
|
||||
workingDirectory: planDir,
|
||||
maxTurns: 10,
|
||||
timeout: 240_000,
|
||||
testName: 'plan-review-prosons-hardstop-neg',
|
||||
runId,
|
||||
model: 'claude-opus-4-7',
|
||||
});
|
||||
|
||||
logCost('/plan-review prosons hard-stop negative', result);
|
||||
recordE2E(evalCollector, '/plan-review-prosons-hardstop-neg', 'Plan Prosons — Hard-stop Negative', result, {
|
||||
passed: ['success', 'error_max_turns'].includes(result.exitReason),
|
||||
});
|
||||
expect(['success', 'error_max_turns']).toContain(result.exitReason);
|
||||
|
||||
expect(fs.existsSync(outFile)).toBe(true);
|
||||
const captured = fs.readFileSync(outFile, 'utf-8');
|
||||
expect(captured.length).toBeGreaterThan(200);
|
||||
|
||||
// Genuine tradeoff — must NOT dodge to hard-stop escape.
|
||||
expect(captured).not.toMatch(HARD_STOP_ESCAPE_RE);
|
||||
// Must have real pros and cons (≥2 ✅ + ≥1 ❌ per option)
|
||||
expect(countChars(captured, '✅')).toBeGreaterThanOrEqual(4);
|
||||
expect(countChars(captured, '❌')).toBeGreaterThanOrEqual(2);
|
||||
}, 300_000);
|
||||
});
|
||||
|
||||
// --- Case 3: Neutral-posture NEGATIVE (CT2) ---
|
||||
|
||||
describeIfSelected('Plan Prosons — Neutral-posture Negative', ['plan-review-prosons-neutral-neg'], () => {
|
||||
let planDir: string;
|
||||
let outFile: string;
|
||||
|
||||
beforeAll(() => {
|
||||
planDir = setupPlanDir('skill-e2e-plan-prosons-neutral-neg-', DOMINANT_PLAN, 'plan-ceo-review');
|
||||
outFile = path.join(planDir, 'ask-capture.md');
|
||||
});
|
||||
|
||||
afterAll(() => {
|
||||
try { fs.rmSync(planDir, { recursive: true, force: true }); } catch {}
|
||||
});
|
||||
|
||||
testConcurrentIfSelected('plan-review-prosons-neutral-neg', async () => {
|
||||
const result = await runSkillTest({
|
||||
prompt: `Read plan-ceo-review/SKILL.md.
|
||||
|
||||
Read plan.md — Option A dominates Option B on coverage. This is NOT a taste call. Pick the approach via AskUserQuestion (Step 0C-bis / Implementation Alternatives — coverage-differentiated, so Completeness: N/10 applies).
|
||||
|
||||
${captureInstruction(outFile)}
|
||||
|
||||
After writing the file, stop.`,
|
||||
workingDirectory: planDir,
|
||||
maxTurns: 10,
|
||||
timeout: 240_000,
|
||||
testName: 'plan-review-prosons-neutral-neg',
|
||||
runId,
|
||||
model: 'claude-opus-4-7',
|
||||
});
|
||||
|
||||
logCost('/plan-review prosons neutral negative', result);
|
||||
recordE2E(evalCollector, '/plan-review-prosons-neutral-neg', 'Plan Prosons — Neutral Negative', result, {
|
||||
passed: ['success', 'error_max_turns'].includes(result.exitReason),
|
||||
});
|
||||
expect(['success', 'error_max_turns']).toContain(result.exitReason);
|
||||
|
||||
expect(fs.existsSync(outFile)).toBe(true);
|
||||
const captured = fs.readFileSync(outFile, 'utf-8');
|
||||
expect(captured.length).toBeGreaterThan(200);
|
||||
|
||||
// One option dominates — must NOT use "taste call" neutral-posture dodge.
|
||||
expect(captured).not.toMatch(NEUTRAL_POSTURE_RE);
|
||||
// (recommended) label MUST be present on the dominant option.
|
||||
expect(captured).toMatch(RECOMMENDED_LABEL_RE);
|
||||
// Recommendation line must contain "because" (concrete reason, not "no preference")
|
||||
expect(captured).toMatch(/[Rr]ecommendation:.*because/);
|
||||
}, 300_000);
|
||||
});
|
||||
|
||||
// --- Case 4: Hard-stop POSITIVE (escape allowed when legitimately one-sided) ---
|
||||
|
||||
describeIfSelected('Plan Prosons — Hard-stop Positive', ['plan-ceo-review-prosons-cadence'], () => {
|
||||
let planDir: string;
|
||||
let outFile: string;
|
||||
|
||||
beforeAll(() => {
|
||||
planDir = setupPlanDir('skill-e2e-plan-prosons-hardstop-pos-', HARDSTOP_PLAN, 'plan-ceo-review');
|
||||
outFile = path.join(planDir, 'ask-capture.md');
|
||||
});
|
||||
|
||||
afterAll(() => {
|
||||
try { fs.rmSync(planDir, { recursive: true, force: true }); } catch {}
|
||||
});
|
||||
|
||||
testConcurrentIfSelected('plan-ceo-review-prosons-cadence', async () => {
|
||||
const result = await runSkillTest({
|
||||
prompt: `Read plan-ceo-review/SKILL.md.
|
||||
|
||||
Read plan.md — this is a destructive one-way action (terminate all sessions). Ask the user to confirm via AskUserQuestion. This is a legitimate hard-stop choice — the hard-stop escape (\`✅ No cons — this is a hard-stop choice\`) is allowed here because there is no meaningful alternative besides doing or not doing the action.
|
||||
|
||||
${captureInstruction(outFile)}
|
||||
|
||||
After writing the file, stop.`,
|
||||
workingDirectory: planDir,
|
||||
maxTurns: 10,
|
||||
timeout: 240_000,
|
||||
testName: 'plan-ceo-review-prosons-cadence',
|
||||
runId,
|
||||
model: 'claude-opus-4-7',
|
||||
});
|
||||
|
||||
logCost('/plan-review prosons hard-stop positive', result);
|
||||
recordE2E(evalCollector, '/plan-ceo-review-prosons-cadence', 'Plan Prosons — Hard-stop Positive', result, {
|
||||
passed: ['success', 'error_max_turns'].includes(result.exitReason),
|
||||
});
|
||||
expect(['success', 'error_max_turns']).toContain(result.exitReason);
|
||||
|
||||
expect(fs.existsSync(outFile)).toBe(true);
|
||||
const captured = fs.readFileSync(outFile, 'utf-8');
|
||||
expect(captured.length).toBeGreaterThan(100);
|
||||
|
||||
// Format scaffolding still required
|
||||
expect(captured).toMatch(PROS_CONS_HEADER_RE);
|
||||
// Hard-stop escape is ACCEPTED here (destructive one-way action)
|
||||
// Either the escape is used OR real pros/cons are present — both are valid.
|
||||
const hasEscape = HARD_STOP_ESCAPE_RE.test(captured);
|
||||
const hasProsAndCons = countChars(captured, '✅') >= 1 && countChars(captured, '❌') >= 1;
|
||||
expect(hasEscape || hasProsAndCons).toBe(true);
|
||||
}, 300_000);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await finalizeEvalCollector(evalCollector);
|
||||
});
|
||||
@@ -566,10 +566,21 @@ describe('v0.4.1 preamble features', () => {
|
||||
const skillsWithPreamble = [...tier1Skills, ...tier2PlusSkills];
|
||||
|
||||
for (const skill of tier2PlusSkills) {
|
||||
test(`${skill} contains RECOMMENDATION format`, () => {
|
||||
test(`${skill} contains AskUserQuestion Pros/Cons format`, () => {
|
||||
const content = fs.readFileSync(path.join(ROOT, skill), 'utf-8');
|
||||
expect(content).toContain('RECOMMENDATION: Choose');
|
||||
// v1.7.0.0 Pros/Cons format tokens. The preamble resolver
|
||||
// (generate-ask-user-format.ts) injects all of these into every
|
||||
// tier-2+ skill. Drop any of them and the test catches it on the
|
||||
// next `bun test` run.
|
||||
expect(content).toContain('AskUserQuestion');
|
||||
expect(content).toContain('Pros / cons:');
|
||||
expect(content).toContain('Recommendation: <choice>');
|
||||
expect(content).toContain('Net:');
|
||||
expect(content).toContain('ELI10');
|
||||
expect(content).toContain('Stakes if we pick wrong:');
|
||||
// Concrete format markers must be documented in the resolver text
|
||||
expect(content).toMatch(/✅/);
|
||||
expect(content).toMatch(/❌/);
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user