@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/brainstorm-techniques/references/decision-principles.md

@@ -0,0 +1,150 @@
+# Decision Principles — Mechanical / Taste / User-Challenge
+
+How a Soleur skill decides, for each **intermediate** decision, whether to
+**auto-answer** it or **surface** it to the operator — without ever adding a
+mid-pipeline pause. Adapted from gstack `autoplan`, narrowed for Soleur's
+non-technical solo-founder operator and all-Claude model policy (ADR-053).
+Decision record: [ADR-084](../../../../../knowledge-base/engineering/architecture/decisions/ADR-084-decision-classification-taxonomy-for-autonomous-question-surfacing.md).
+
+Consumed by: `brainstorm-techniques`, `plan` (Step 4.5), `work` (emergent
+decisions), and `ship` (Phase 6, which renders the headless record). `one-shot`
+inherits via those skills and is deliberately not edited (mirrors ADR-083).
+
+## The 2 surfacing principles
+
+Only the principles that decide **surface vs. auto-answer** live here. Code-taste
+(how to write the code once you've decided to auto-answer) is governed by the
+[constitution](../../../../../knowledge-base/project/constitution.md) and YAGNI —
+not restated here.
+
+1. **Blast-radius** — a change that is in the plan's blast radius (files it
+   touches + their direct importers) AND small (`< 1 day` / `< 5 files` / no new
+   infra) is auto-decide-eligible. Outside the radius, or larger, lean toward
+   surfacing.
+2. **Bias-to-action** — flag concerns but do not block; **never** insert a
+   mid-pipeline pause to ask. Surfacing happens at an *existing* gate or via a
+   recorded artifact, never a new stop.
+
+## Classification — by consequence, not surface-flavor
+
+Classify each decision by what its outcome *costs the operator*, not by whether
+it looks technical.
+
+- **Mechanical** — one clearly-right answer, OR a purely-technical choice a
+  non-technical operator cannot evaluate (which abstraction, which query shape,
+  which test helper). **Auto-decide silently.**
+- **Taste (user-legible)** — a **user-visible OR money/compliance** choice where
+  reasonable operators could disagree. Auto-decide with a recommendation, and
+  surface it (see the mode table). "Money/compliance" explicitly includes: a new
+  external **sub-processor**, a new **recurring cost**, new **data egress**, or a
+  **lawful-basis** change.
+- **User-Challenge** — both signals (see below) agree the operator's **stated
+  direction** should change (merge, split, add, or drop a feature/scope the
+  operator specified). **Never auto-decided.** The operator's direction is the
+  default; the signals must make the case for change.
+
+### Four NEVER-Mechanical classes (even when they present as technical)
+
+These *look* like implementation details but carry user-visible / money /
+compliance consequence — they are never Mechanical:
+
+1. **Dropping or deferring operator-requested scope** (a YAGNI/bias-to-action
+   cut of something the operator asked for).
+2. **Onboarding a new external sub-processor or paid dependency.**
+3. **A new recurring operational cost** (a higher token/API tier, a new
+   subscription).
+4. **Irreversible or destructive operations on user data** (dropping a column,
+   a lossy format change).
+
+Blast-radius / bias-to-action **never** override these four — a small, in-radius
+scope cut of operator-requested work is still a Taste/User-Challenge surface.
+
+### Precedence — technical rulings go to the CTO, not the operator
+
+A technical ruling (schema/audit substrate, data model, technology choice, security model, which load-bearing module to
+disturb, a threshold or evidence bar, which of two designs, whether evidence suffices, a status flip) routes to the
+`soleur:engineering:cto` agent (legal posture: `soleur:legal:clo`) in **both** modes and is recorded `Ruled by CTO agent`.
+It is not a User-Challenge even when user-visible or consequential. The four NEVER-Mechanical classes above decide
+whether the session model may **auto-decide**; they never decide **who rules**. This taxonomy governs product / scope /
+preference decisions only, never *how* to build. The closed operator-only list, the delegation step, the recording
+format and the override for a "surface it" brief live in
+`technical-ruling-delegation.md` (the `brainstorm-techniques` skill's references).
+
+## Mode-branched resolution (keyed on execution context, not skill name)
+
+**Mode = execution context.** *Operator-attached* means a real operator TTY is
+present: a direct `soleur:brainstorm` or `soleur:plan` run, `HEADLESS_MODE`
+unset, not invoked with a plan-file argument, and **not inside a Task subagent**.
+Any Task-subagent context (a `plan` consult, all of `one-shot`) is **headless**
+regardless of the parent skill — a subagent gets prompt text only and cannot call
+`AskUserQuestion` ([task-subagent-prompt-text-only](../../../../../knowledge-base/project/learnings/best-practices/2026-05-12-task-subagent-prompt-text-only.md); guarded at `plan` Step 2.5). A subagent
+returns any surface-worthy decision to its parent as structured text.
+
+| Class | Operator-attached (real TTY) | Headless (no attached operator, incl. any subagent / one-shot) |
+|---|---|---|
+| Mechanical | auto-decide silently | auto-decide silently |
+| Taste (user-legible) | auto-decide + recommend; fold into the **existing** gate if one remains, else append to the run's output artifact (brainstorm decisions / plan `## Decisions Auto-Made`) — never a new pause | auto-decide + **persist to the challenges artifact** (see below) |
+| User-Challenge | `AskUserQuestion` at the existing final gate (in `plan`, the post-`plan-review` confirmation), using the 5-line frame below | keep operator's **stated direction (default)** + **persist to the challenges artifact**; never pause |
+
+### The challenges artifact + its legible surface
+
+Headless Taste(user-legible) and User-Challenge decisions are **persisted**, not
+paused on. The producer (`work`, or `plan` Step 4.5 in a subagent) appends to
+`knowledge-base/project/specs/<branch>/decision-challenges.md` (alongside
+`session-state.md`). At ship time, `ship` Phase 6 reads that artifact and:
+
+1. Folds it into the canonical PR body under a heading **outside** the
+   `ship-operator-step-gate` deny set (`Operator`/`Post-merge`/`Follow-up`) and
+   with **no operator-action bullets** — informational statements only (e.g.
+   `## Model Dissents (informational)`).
+2. Opens **one** idempotent GitHub issue labelled `action-required` +
+   `decision-challenge`, plain-language title linking the PR — because
+   `operator-digest` harvests `action-required` *issues* (Section 4), never PR
+   bodies. This is the surface the non-technical operator actually sees. The
+   issue covers **operator-class rows only**; technical rows render in the PR body
+   with their `Ruled by` lines and never reach the operator.
+
+The PR-body block is the durable record; the `action-required` issue is the
+legible surface for operator-class items. Both are required for a headless
+operator-class challenge.
+
+**The artifact carries a `## Decision Classes` table** (columns `Item | Class | Ruling`, one row per persisted decision,
+whatever shape the free-form body uses; `Class` is `technical`, `taste` or `operator (<category>)`). The schema, the closed
+category list and a canonical example are in `technical-ruling-delegation.md` (the `brainstorm-techniques` skill's references)
+(section 6); `ship`'s Technical-Ruling Gate scans every such table (plus a file-wide placeholder and label lint).
+
+### User-Challenge 5-line frame
+
+When surfacing (attached) or persisting (headless) a User-Challenge, use:
+
+- **What you said:** the operator's original direction.
+- **What both signals recommend:** the proposed change.
+- **Why:** the signals' reasoning.
+- **What context we might be missing:** explicit blind-spot acknowledgment.
+- **If we're wrong, the cost is:** what happens if the operator's original
+  direction was right and we changed it.
+
+**A premise that is a universal negative must ship with the enumeration that produced it, not just the conclusion.** When a challenge's framing rests on "there is no X in state S" (no reachable affordance, no existing caller, no other writer), specific verified facts about *particular* members — `this variable is dead`, `that flag is unconditional` — cannot establish a claim quantified over the *category*, however many you list. Put the command and its result in the challenge (`git grep -n 'aria-label="Back' -- <scope>` → N renderers, each classified), because the operator is being asked for taste and reasonably assumes the facts framing the choice were established; an approval laundered through a false premise acquires human authority while remaining an unverified engineering claim, and every downstream artifact — wireframe, plan, challenges file, code comment, and the test that "guards" it — inherits it. If the premise is later falsified, correct it **where the approval lives** (a dated `CORRECTION` block in `decision-challenges.md` saying what it does and does not change), never silently in code. **Why:** #7186 — DC1 was approved on "the mobile KB landing has no reachable in-page back at all today"; review found a fourth renderer in a file the enumeration never opened, so the shipped state has two links sharing one accessible name.
+
+## "Both signals" — scope, disagreement, and the security exception
+
+**Both signals = the session model + the ADR-083 scoped `fable`→`opus` consult**,
+and only at the two gates where that consult already fires: `plan` Step 4.5 and
+`ship` Phase 5.5. Elsewhere (e.g. `work` emergent decisions) there is a **single**
+signal — the session model + this surface criterion. **Do not add a new
+per-decision consult** (that would balloon ADR-083's scoped 2-gate consult into
+cost/latency creep).
+
+- **Disagreement:** when the two signals disagree at a gate, promote the item to
+  the recorded/surfaced tier (a Taste item becomes a persisted/surfaced one). The
+  operator's stated direction stays the default regardless.
+- **Ambiguity fail-safe defaults:** unsure Mechanical-vs-Taste **and** the
+  decision is user-visible/money/compliance → treat as **Taste**. Unsure
+  Taste-vs-User-Challenge → treat as **User-Challenge** (bias to the more-surfaced
+  class; the cost of over-recording is one label).
+- **Security/feasibility exception — the SOLE deviation from no-pause.** When a
+  decision introduces an auth/secret/data-exposure regression, or makes the
+  stated approach technically infeasible (not a mere preference): attached →
+  urgent-framed `AskUserQuestion`; headless → **terminal halt before merge** (a
+  stop, not a mid-pipeline pause) + an `action-required` + `security` issue. This
+  is the only exception to bias-to-action's no-pause rule.

package/skills/brainstorm-techniques/references/phase-boundaries.md

@@ -0,0 +1,103 @@
+<!-- Adapted from mattpocock/skills/skills/engineering/ask-matt/PHASE-BOUNDARIES.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+
+# Phase Boundaries — choosing between Continue, `/clear`, handoff, subagent and `/compact`
+
+A **phase** is a chunk of work inside a session: the brainstorm, the plan, the implementation, the
+QA. The definition is deliberately fuzzy — a phase ends at the moment the work reads as *"that part
+is done"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs.
+Mid-phase there is nothing to decide: continue, or split off what is left into a subagent.
+Compacting mid-phase makes the session lose the thread of the work it is in the middle of.
+
+This is a reference, not a gate. It carries the reasoning; the always-loaded rule
+`cm-when-proposing-to-clear-context-or` carries the obligation.
+
+## The five options
+
+| Option | What it does |
+|---|---|
+| **Continue** | Stay in this session. No context switch at all. |
+| **`/clear`** | Empty the context window and start from nothing. The old session stays resumable. |
+| **Handoff** | Write a portable resume prompt or markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back. This session is untouched. |
+| **`/compact`** | Compress this context and continue from the summary. |
+
+## The tree
+
+Work top to bottom at the boundary. **The first *yes* wins.** Do not score the options against each
+other — ask the questions in order and stop at the first one that answers yes.
+
+### 1. Can the work continue in this session?
+
+Two things make the answer yes:
+
+- The next phase needs this phase as a **primary source** — it wants the reasoning verbatim, not a
+  summary of it. Brainstorm → plan and plan → work are the standard yeses.
+- There is enough context window left for the next phase to fit.
+
+**Rule this out first.** Continue costs nothing and loses nothing: it is the only option on the board
+that does not convert a primary source into a secondary one. Every question below is paid for with
+lossiness, so none of them is worth asking until this one is answered no.
+
+### 2. Is everything in this session irrelevant to what comes next?
+
+If the exploration, the decisions and the dead ends are all disposable — **`/clear`**. It is the
+cheapest move after Continue: it takes no time and returns the whole window, and the cleared session
+stays resumable.
+
+The cost of getting this one wrong is one-way. Clear a *relevant* context and the **why** behind what
+was built is gone; re-reading the diff does not give it back.
+
+### 3. Does the work need to travel?
+
+**Handoff** is narrow. It is needed only when the work is:
+
+- moving to a **different harness** (Claude Code → Devin, Codex, Grok Build),
+- moving to a **different directory, worktree or repository**,
+- going to **another person**,
+- or forking a side task found mid-phase without derailing what is in progress.
+
+That list is the whole clause. What a handoff buys is **portability** — an artifact that travels. If
+nothing is travelling, it is not needed. In this repo the handoff artifact is the copy-pasteable
+resume prompt required by `cm-when-proposing-to-clear-context-or` and `wg-end-of-work-emit-resume-prompt`:
+skill or command, plan path, branch, worktree path, PR number, issue number, one-line summary.
+
+### 4. Can the task run unattended?
+
+Is it scoped tightly enough to run with nobody steering it? Then send it to a **subagent** and leave
+this session untouched. Read-and-report work is the standard case: a review agent reads the diff and
+reports back, and nothing in this session has to change to let it. `cm-delegate-verbose-exploration-3-file`
+already mandates this shape for verbose exploration, which is the most common instance.
+
+### 5. Otherwise, `/compact`.
+
+Relevant context, same harness, same directory, and the session must stay in the loop: this is where
+the tree lands, and it lands here often. Pass an instruction with it (`/compact we are about to QA
+this area`) so the summary keeps what the next phase needs.
+
+**`/compact` is the default, not the first reach.** It sits last because the four questions above it
+are each cheaper or more precise. The failure mode when a session starts here is a fresh context that
+is confidently wrong about a decision the summary flattened.
+
+## Why Continue is ruled out first: primary and secondary sources
+
+Every option except **Continue** turns a **primary source** into a **secondary source** — the session
+as it actually happened, replaced by a description of it. The trade always has the same shape:
+
+| Source | Information | Noise | Room to move |
+|---|---|---|---|
+| Primary (Continue) | Full | High | Little |
+| Secondary (`/compact`, handoff, `/clear`, subagent report) | Lossy | Low | Lots |
+
+A secondary source is not a worse source — it is a *different* one. It has less noise and leaves more
+window to work in, which is exactly why the lower branches of the tree exist. But it cannot be turned
+back into a primary source, and the loss is invisible: a flattened summary reads as confident and
+complete. That asymmetry is the whole reason question 1 comes first. Pay the lossiness only when
+staying costs more than it saves.
+
+## These are judgement calls
+
+None of the five questions is objective; each has taste in it, and the same boundary can go two ways
+on two different days. The value is in asking them **in order**, **at the boundary** rather than in
+the middle of the work.