@gobing-ai/spur 0.3.41 → 0.3.42

package/plugins/sp/skills/spur-dev/references/decision-brief.md

@@ -0,0 +1,80 @@
+---
+name: decision-brief
+description: "Extracted format: the HITL decision-brief shape used wherever the pipeline asks the operator to choose — brainstorm clarification, dev-refine questions, and the decomposition pre-batch quiz. One SSOT so every human-facing choice reads the same way."
+see_also:
+  - spur-dev
+  - brainstorm
+  - spec-decomposition
+---
+
+# Decision-Brief Format (HITL SSOT)
+
+When the pipeline surfaces a choice to the operator, present it as a **decision brief**, not a bare
+question. The brief respects the operator's time: it leads with the question and a recommendation, so
+a busy reader can approve in one glance or dive into the options if they disagree. This is the single
+source of truth — `brainstorm` (clarify), `dev-refine` (questions), and the `spec-decomposition`
+pre-batch quiz all render their prompts in this shape; they link here rather than restating it.
+
+## The shape
+
+Every decision brief carries, in order:
+
+1. **One-line question.** The decision in a single sentence. No preamble.
+2. **Stakes, in plain English.** Why it matters and what a wrong pick costs — reversibility, blast
+   radius, who is affected. One or two sentences, no jargon.
+3. **A recommendation — always.** State which option you would pick and why, in one line. "It
+   depends" is not an answer; if it depends, name what it depends on. The operator can override, but
+   they should never have to guess what you think.
+4. **Options with a completeness score.** For each option, a `0–100` completeness score (how fully it
+   solves the stated problem). When options differ **in kind** (not in degree) a single score
+   misleads — replace it with a one-line **kind-note** describing the axis of difference instead.
+5. **Pros / cons per option.** The two or three that actually move the decision — not an exhaustive list.
+6. **Dual effort labels where effort differs.** Label human effort and AI effort separately
+   (e.g. `human: 5 min review · AI: 2 min`) **only when they diverge**. If effort is comparable,
+   omit — the label exists to surface where the human cost and the agent cost pull apart.
+
+## Template
+
+```
+Q: <one-line question>
+Stakes: <plain-English cost of a wrong pick; reversibility / blast radius>
+Recommendation: <the option you'd pick> — <one-line why>
+
+Option A — <name>   [completeness: 85]   [human: 5 min · AI: 2 min]
+  + <pro that moves the decision>
+  − <con that moves the decision>
+Option B — <name>   [kind-note: optimizes for X over Y, not "more/less complete"]
+  + <pro>
+  − <con>
+```
+
+## Rules
+
+- **Recommendation is mandatory.** A brief that lists options without a recommendation offloads the
+  decision the agent was asked to help with. Pick one; defend it in a line.
+- **Score, or kind-note — never a false score.** Do not assign a completeness number to options that
+  differ in kind; a `70 vs 72` on incommensurable options is noise. Use the kind-note.
+- **Effort labels only where they diverge.** Adding `human: 2 min · AI: 2 min` everywhere is clutter;
+  the signal is the *divergence* (a change that is cheap for the AI but expensive for the human to
+  review, or vice-versa).
+- **Plain English in the stakes.** The operator may not share the agent's context; state the cost in
+  terms they can weigh without reading the code.
+- **Tool-call rendering where available.** Where a structured-input tool exists (`AskUserQuestion`
+  on Claude Code, or the platform equivalent), render the brief *as* the tool's option array —
+  recommendation → `recommended` field, options → `options[]`, scores / pros / cons folded into each
+  option's description. Do not double-render (markdown text + tool call) — pick one channel; the
+  tool wins. Render the markdown template above only when no structured-input tool is available.
+
+## Where it is applied
+
+| Site | Prompt | How the brief is used |
+|---|---|---|
+| `brainstorm` (dev-brainstorm Phase 1) | clarify ambiguous input | Each `AskUserQuestion` is framed as a decision brief — recommendation + option scores. |
+| `dev-refine` | targeted Q&A on gaps | Each refinement question presents the options as a brief so the operator picks with stakes visible. |
+| `spec-decomposition` pre-batch quiz | approve the task breakdown | The granularity / dependency quiz is a decision brief: recommended breakdown + the trade-off of each alternative slicing. |
+| `dev-plan` intake | scope, constraints, success (design package via `--skip-design` only) | Single `AskUserQuestion` call with multiple questions — one per independent dimension. Recommendation and scored options per dimension. |
+| `dev-idea` intake | idea scope, feature, success (design package via `--skip-design` only) | Single `AskUserQuestion` call with multiple questions — one per independent dimension. Recommendation and scored options per dimension. |
+| `dev-idea` idea-eval | approve enhanced idea / reject (no feature) | Taste HITL after discovery: report at `.spur/run/idea-eval-report.md` (urgency/necessity, premises, pros/cons). Not auto-clicked by `--auto` unless taste pre-cleared (`--approve-taste`). |
+| `dev-wrap` branch cleanup | merge strategy, target, cleanup scope | Single `AskUserQuestion` call — asked even under `--auto` (irreversible). Confirmation collects all parameters up front. |
+| `dev-wrapall` batch branch cleanup | merge strategy, target, scope, feature transition | Single `AskUserQuestion` call — asked even under `--auto` (irreversible). Confirmation collects all parameters up front. |
+| `dev-refine` focus selection | `--focus` bundle selection | Single `AskUserQuestion` call with one question per focus dimension. Scored choices from the decision brief become `options[]`. |