@fro.bot/systematic 2.25.0 → 2.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/ce-brainstorm/SKILL.md

@@ -179,14 +179,31 @@ If relevant, call out whether the choice is:
 - Extend an existing capability
 - Build something net new
 
+### Phase 2.5: Synthesis Summary
+
+**STOP. Before composing the synthesis, read `references/synthesis-summary.md`.** The two-stage shape (internal three-bucket draft → chat-time scoping synthesis), the Path A / Path B gate, the four scoping synthesis sections with their keep tests, the tier-aware bullet budget with re-cut rule, anti-pattern guidance, soft-cut behavior, self-redirect support, and headless-mode routing all live there. Composing a synthesis without these rules loaded reliably produces malformed output — pasting the full internal three-bucket draft verbatim into chat, implementation-detail leakage into the scoping synthesis, the proposal-pitch anti-pattern. **Each scoping synthesis bullet must pass the affirmability test (can the user evaluate this without reading code?) AND the detail test (1–2 lines max, conversational not documentary); over-share and over-detail are the failure modes to avoid.** This is not optional supplementary reading; it is the source of truth for how the phase behaves.
+
+Surface a scoping synthesis to the user before Phase 3 writes the requirements doc — the user's last opportunity to correct scope before the artifact lands. **Phase 2.5 is the only scope gate in this workflow.** The scoping synthesis is shaped like what two product collaborators would confirm before writing a PRD, not like a comprehensive audit or a one-line preview.
+
+Fires for **all tiers** including Lightweight. Skip Phase 2.5 entirely on the Phase 0.1b non-software (universal-brainstorming) route.
+
+**Path A vs Path B:** the scoping synthesis shape depends on TWO signals — whether any blocking question fired AND what tier Phase 0.3 classified the scope as.
+
+- **Path A — no blocking questions fired AND tier is Lightweight**: announce-mode. Emit "What we're building" prose only (1–3 sentences), then proceed to Phase 3 doc-write in the same turn. No other sections, no confirmation question. Do NOT end the turn waiting for acknowledgment. The user can revise after the doc lands if the shape is wrong — Lightweight Path A docs are short, post-hoc revision is cheap.
+- **Path B — at least one blocking question fired, OR tier is Standard / Deep-feature / Deep-product**: full tier-aware scoping synthesis with confirmation gate. Two scenarios fire Path B: (a) the user invested answer-time during dialogue, or (b) the user pre-loaded substantive scope content (Phase 0.2 fast-path with a richly-specified opening prompt). Either way, the substance earns a real checkpoint. Confirmation is unconditional even when zero call-outs survive the keep test.
+
+**Why the tier guard on Path A**: Phase 0.2's fast path serves two very different cases — a tight one-liner that needs no dialogue ("fix the typo on line 47") and a richly pre-loaded brainstorm context that ALSO needs no dialogue because the user pre-stated everything. Without the tier guard, both route to Path A and the pre-loaded case gets a 1-sentence checkpoint for what may be 20+ items worth of scope. Tier-classifying Phase 0.3 distinguishes the two — pre-loaded substance makes the tier Standard or Deep, which then routes to Path B.
+
 ### Phase 3: Capture the Requirements
 
-Write or update a requirements document only when the conversation produced durable decisions worth preserving. Read `references/requirements-capture.md` for the document template, formatting rules, visual aid guidance, and completeness checks.
+Write or update a requirements document only when the conversation produced durable decisions worth preserving. Read `references/requirements-capture.md` for the document template, formatting rules, visual aid guidance, and completeness checks. Read `references/brainstorm-sections.md` for metadata field contracts and ID conventions. Read `references/markdown-rendering.md` for markdown presentation principles.
 
 For **Lightweight** brainstorms, keep the document compact. Skip document creation when the user only needs brief alignment and no durable decisions need to be preserved.
 
 ### Phase 3.5: Document Review
 
+**This is a quality and format review of the written artifact — not a second scope negotiation.** Scope was confirmed at Phase 2.5; Phase 3.5 checks that the written doc faithfully reflects that confirmed scope and meets quality standards. Do not re-open scope decisions here.
+
 When a requirements document was created or updated, run the `document-review` skill on it before presenting handoff options. Pass the document path as the argument.
 
 If document-review returns findings that were auto-applied, note them briefly when presenting handoff options. If residual P0/P1 findings were surfaced, mention them so the user can decide whether to address them before proceeding.

package/skills/ce-brainstorm/references/brainstorm-sections.md

@@ -0,0 +1,50 @@
+# Brainstorm Sections
+
+This reference describes the rendering and ordering conventions for brainstorm
+requirements documents. It does NOT prescribe which sections exist or what they
+must contain — section inventory, content rules, and the document template live
+in `references/requirements-capture.md`.
+
+Rendering is handled by `references/markdown-rendering.md`.
+
+## Brainstorm metadata fields
+
+Every brainstorm carries a small set of stable metadata fields that
+downstream tooling depends on. The contract is format-independent: these
+fields appear as YAML frontmatter at the top of the file. Field names and
+semantics are stable so consumers can locate them without knowing which
+session produced the brainstorm.
+
+### Required
+
+- **`date`** — creation date in ISO 8601 (`YYYY-MM-DD`), ASCII digits only.
+  Used in the filename (`docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md`).
+- **`topic`** — kebab-case slug identifying the brainstorm subject (e.g.,
+  `surface-scope-earlier`, `demo-reel-local-save`). Used in the filename
+  alongside `date` and as the resume-detection key when `ce-brainstorm`'s
+  Phase 0.1 scans `docs/brainstorms/` for an existing artifact to continue.
+
+### Status flip does not apply to brainstorm
+
+Unlike plans, brainstorm artifacts have no `status` field — there is no
+`active → completed` lifecycle. A brainstorm is a one-time output that
+downstream consumers (`ce-plan`, `document-review`) reference via the plan's
+`origin:` field.
+
+### Field-name stability
+
+Field names are stable across brainstorm revisions — never rename a field
+or repurpose its semantics. Agents composing new brainstorms MUST use these
+exact names; adding new fields is fine, but renaming `topic` to `subject`
+or `date` to `created` breaks filename construction and resume detection.
+
+> **Section inventory, content rules, and the Summary vs Problem Frame discipline are owned by `references/requirements-capture.md`; this file covers rendering conventions and metadata contracts only.**
+
+## Rendering
+
+The format-specific reference describes how to render these sections:
+
+- **Markdown rendering:** `references/markdown-rendering.md`
+
+This reference (`brainstorm-sections.md`) is about rendering conventions and
+metadata contracts; section content rules live in `references/requirements-capture.md`.

package/skills/ce-brainstorm/references/markdown-rendering.md

@@ -0,0 +1,202 @@
+# Markdown Rendering
+
+This is a format-rendering reference — it describes how to render any
+artifact in markdown, independent of which skill is producing it.
+
+It is paired with a section contract (`references/brainstorm-sections.md`)
+that describes *what* the artifact contains. This reference describes *how*
+markdown specifically presents it.
+
+## Hard invariants
+
+These hold regardless of which skill produced the artifact.
+
+- **YAML frontmatter at the top of the file.** Standard `---` delimited block
+  containing the artifact's stable metadata (title, status, date, type, etc.
+  — exact fields are per-skill, defined in the section contract). Editable
+  in place; tools and agents that do status flips (`active → completed`)
+  update the YAML directly.
+- **ASCII identifiers in anchors.** Markdown headings auto-generate anchors
+  from the heading text. Keep headings ASCII so anchors are predictable
+  (`#implementation-units`, not `#implementación-units`).
+- **Repo-relative paths for file references.** Always. Never absolute paths
+  — they break portability across machines, worktrees, teammates.
+- **No HTML mixed in.** Keep the markdown pure. No `<div>`, no `<details>`,
+  no inline `<style>`. Markdown stays markdown.
+
+## Format principles
+
+These shape what "good" markdown looks like; the agent applies them per
+artifact based on content shape.
+
+### ID prefix format
+
+Stable IDs (R, U, A, F, AE, KTD) appear as plain prefixes at the start of
+the bullet or heading — do NOT bold the prefix. The prefix is visually
+distinctive on its own; bolding it inflates visual noise.
+
+```markdown
+- R1. The plan returns paginated sessions.   ← right
+- **R1.** The plan returns paginated sessions.   ← wrong (bolded prefix)
+```
+
+Same applies to unit headings: `### U1. Cloak detection in preflight contract`.
+
+### Content shape: prose vs bullets vs tables
+
+The same content can be rendered three ways; the agent picks per content
+shape, not by template default.
+
+- **Prose** when the content has narrative flow (motivation, decision
+  rationale, problem framing). Bullets fragment narrative into
+  disconnected pieces.
+- **Bullets** when items share a parallel shape but each carries enough
+  prose to not fit a table cell.
+- **Tables** when 5+ items share uniform structure (`ID + body`,
+  `name + value`, `decision + rationale`, `risk + mitigation`). Tables
+  scan faster at that scale and unlock additional columns (status,
+  traceability, severity) that bullets can't accommodate cleanly.
+
+The test: which shape would a reader scan fastest for this content? If
+items have parallel structure and 5+ instances, table. If items are 3-5
+and each has a few lines of prose, bullets. If the content is a single
+narrative thought, prose.
+
+### Bold leader labels within bullets
+
+When a bullet has substructure that benefits from named fields (Key Flows
+with Trigger / Actors / Steps / Outcome, Acceptance Examples with Covers
+/ Given / When / Then), use bold leader labels at the start of nested
+bullets — not deeper heading levels.
+
+```markdown
+- F1. Anonymous capture
+  - **Trigger:** Agent enters Step 2a with no session.
+  - **Actors:** A1, A2
+  - **Steps:** Preflight detects cloak; agent launches; capture proceeds.
+  - **Covered by:** R1, R2, R5
+```
+
+This gives the bullet structure without needing H4/H5 headings that would
+clutter the doc and break TOC generation.
+
+### Section separators
+
+For substantial artifacts, use horizontal rules (`---`) between top-level
+H2 sections. Omit for short docs where separators would dominate.
+
+### Tables for genuinely comparative info only
+
+Use tables for the uniform-shape case in "Content shape" above. Don't use
+tables to render content lists that are really bullets — markdown tables
+are noisier in raw form and worse for diffs.
+
+## Section anatomy
+
+How section types commonly render in markdown. These are patterns, not
+contracts — the agent picks the shape that fits the content.
+
+- **Summary / Problem Frame** — prose paragraphs.
+- **Requirements** — bullets with `R<N>.` prefix. When requirements span
+  more than one concern, grouping under bold inline headers is the default
+  shape, not optional polish (group by capability, not by discussion order);
+  render a flat list only when every requirement is about the same thing.
+  When requirements have status, traceability, or severity that warrant
+  additional columns, escalate to a table.
+- **Implementation Units** — H3 heading per unit with `U<N>.` prefix.
+  Fields (Goal, Files, Patterns, Test Scenarios, Verification) render as
+  bullets with bold leader labels, or as sub-headings if the field has
+  multi-paragraph content.
+- **Key Technical Decisions** — bullets with bold decision name + prose
+  rationale, or numbered KTD-N pattern when traceability matters.
+- **Key Flows / Acceptance Examples** — bullets with bold leader labels
+  (Trigger / Actors / Steps / Outcome / Covers / Given-When-Then).
+- **Scope Boundaries** — bullets, optionally split into "Deferred for
+  later" / "Outside this product's identity" sub-headings when the
+  positioning distinction matters.
+
+The agent picks more elaborate or simpler shapes based on what each
+specific artifact's content needs.
+
+## Diagrams
+
+When the section contract calls for a diagram (architecture, sequence,
+flowchart, state machine, swim lane, data-flow), markdown renders it as
+a fenced mermaid block:
+
+```markdown
+` ``mermaid
+flowchart TB
+  A[Start] --> B{Decision}
+  B -->|yes| C[Action]
+  B -->|no| D[Other action]
+` ``
+```
+
+(`TB` direction default — keeps diagrams narrow in source view and in
+narrow rendered viewports.)
+
+For quantitative comparisons (bar charts, scatter plots) markdown has no
+native equivalent — use a table with the data and let prose or caption
+carry the interpretation.
+
+## Inline code and code blocks
+
+- **Inline code** for identifiers (variable names, function names,
+  flag names, file paths, IDs that aren't section anchors).
+- **Fenced code blocks** with language tag for code, shell commands,
+  API request/response samples. Always specify the language for syntax
+  highlighting and accessibility.
+
+```markdown
+The flag `--cdp-url` accepts a URL.
+
+` ``bash
+browser-use --cdp-url http://localhost:9222
+` ``
+```
+
+## No process exhaust
+
+Engineering process metadata stays out of the artifact:
+
+- No "captured at Phase X" notes
+- No `## Next Steps` pointing to the next skill
+- No italic provenance lines ("*Brainstorm completed 2026-05-13*")
+- No engineering-flow shepherding ("Now read this file:", "Next, run that
+  command:")
+
+This information belongs in commit messages, tool output, and agent
+transcripts — not in the artifact a reader returns to weeks later.
+
+## Frontmatter shape
+
+Per-skill frontmatter fields are defined in each skill's section contract
+(`references/brainstorm-sections.md` lists brainstorm frontmatter). Common rules:
+
+- YAML at the top of the file, delimited by `---` on its own line above
+  and below.
+- Field names in lowercase snake_case (`status`, `created_at`, not
+  `Status`, `CreatedAt`).
+- **Status lifecycle is per-contract.** When the section contract
+  defines a `status` field with a lifecycle (plans use
+  `active → completed`, flipped by ce-work at shipping time via direct
+  YAML edit), it is editable in place. When the section contract does
+  not define a status lifecycle (brainstorms have no `active → completed`
+  flip — they are upstream of plans and referenced via the plan's
+  `origin:`), do not introduce one.
+- Stable across artifact revisions — never rename or repurpose a field.
+
+## Post-write audit
+
+Before declaring the markdown file written, scan it for these common
+slips:
+
+- All stable IDs are plain-prefix format, not bolded.
+- No HTML elements mixed in.
+- All file paths are repo-relative.
+- Horizontal rule separators between H2s (for Standard / Deep artifacts).
+- No process exhaust (Phase X notes, Next Steps pointers, provenance
+  lines).
+- Tables only where 5+ uniform-shape items justify them.
+- Frontmatter has all the per-skill required fields with reasonable values.

package/skills/ce-brainstorm/references/requirements-capture.md

@@ -24,6 +24,7 @@ The requirements document is for product definition and scope control. Do **not*
 | Key Decisions | Include when material | Include when material | Include when material |
 | Dependencies / Assumptions | Include when material | Include when material | Include when material |
 | Outstanding Questions | Include when material | Include when material | Include when material |
+| Sources / Research | Include when material | Include when material | Include when material |
 
 ## Summary vs Problem Frame discipline
 
@@ -48,6 +49,25 @@ In the truly-trivial Lightweight case where Summary is skipped (synthesis ≤ 2
 
 **Acceptance Examples** — include when a requirement's behavior is hard to pin down without a concrete scenario. **Always include AEs covering behavioral-conditional requirements** — any requirement framed as "When X, Y" or "If X, Y" — regardless of tier. Conditional framing signals state-dependent behavior, which is exactly where prose alone leaves implicit ambiguity (e.g., "When `--quiet` is set, errors continue to surface" — does that include warnings? does it include binary-side errors? AE pins it down). Each example disambiguates one or more requirements via a `Covers: R-IDs` back-reference. Non-conditional requirements may be omitted unless ambiguity surfaces in review; the section is not exhaustive.
 
+**Sources / Research** — surface research that orients the planner or justifies framing choices. The test: *"if I were the planner reading this cold, would this breadcrumb help me make better choices?"* Yes → surface (code locations, external docs, RFCs, constraints, prior plans — the category is inclusive, not enumerated). Process exhaust (reading the user's prompt, glancing at obvious files) → omit.
+
+## Prose economy
+
+A section can be material and still be written loosely — the failure mode is a material section padded into a wall of text where contradictions hide and a downstream agent loses the thread. Length that earns its place is fine; wordiness around that length is not.
+
+Hold every kept section to these:
+
+- **One idea per sentence.** A Summary is a handful of sentences, not one sentence with five semicolons and four parentheticals. If a sentence needs a second parenthetical to stay true, split it.
+- **A requirement is one sentence of intent plus at most one qualifier.** When a requirement would specify two outcomes ("either A or B, planning decides"), state the intent and send the fork to Outstanding Questions — don't write both arms in full inside the requirement.
+- **Cut hedges and intensifiers.** "Critically", "deliberately", "explicitly", "genuinely", "actually", "simply" carry nothing a downstream agent acts on.
+- **Prefer the verb to the nominalization.** "Demote the grid", not "the demotion of the grid is the deliberate change in this brief".
+
+Precision is not padding: keep domain terms, conditionals, and exact thresholds verbatim. Economy targets the connective tissue around them, never the precision itself.
+
+**Resolve in place; don't stratify.** When a later decision answers a parked question or supersedes earlier text, rewrite or remove the original entry — don't append a separate "resolutions" layer that leaves the superseded text standing. Version control holds the history. Stacked question/resolution strata double the reading surface and hide which text is live.
+
+**Named test, run before the doc is declared written:** could a reader find a contradiction in each section in one pass? A sentence carrying more than one parenthetical, or a requirement specifying two outcomes, fails the test — split it or defer it.
+
 ## Template
 
 Use this template and omit sections per the matrix above. At Deep-product tier, keep the Scope Boundaries split. At other tiers, use the single Scope Boundaries list.

package/skills/ce-brainstorm/references/synthesis-summary.md

@@ -0,0 +1,273 @@
+# Synthesis Summary
+
+**Synthesis ≠ requirements doc.** The synthesis is NOT a preview, draft, or substitute for the requirements doc — it's the scope checkpoint that doc-write consumes as input. The requirements doc itself is written in Phase 3 from the confirmed synthesis. Both the synthesis and the requirements doc stay scope-only — implementation detail (file paths, code shapes, exact error wording) is downstream (ce-plan's job), not the requirements doc.
+
+**Two-stage shape: internal draft, then chat-time scoping synthesis.** The synthesis is composed in two stages. Stage 1 is an internal three-bucket draft (Stated / Inferred / Out of scope) the agent uses to think comprehensively about scope. Stage 2 is the scoping synthesis presented to the user — shaped like what two product collaborators would confirm before writing a PRD, not like a comprehensive audit and not like a one-line preview. The user only sees stage 2. The internal draft still informs the doc body via the doc-shape routing below; it just doesn't reach the user verbatim. This split exists because the comprehensive audit shape produced too much detail for the user to actually weigh in on, even when the granularity rules were followed.
+
+**Three-bucket structure is the internal draft, not the user-facing artifact.** It does its scope-thinking job during stage 1 and dissolves when Phase 3 writes the doc: Stated content informs Requirements, Inferred content informs Key Decisions, Out-of-scope content informs Scope Boundaries. The doc has no parallel `## Synthesis` section — only the scoping synthesis prose embeds, as `## Summary`. See "Doc shape after confirmation" below for the routing.
+
+This content is loaded when Phase 2.5 fires — after Phase 2 (approaches chosen) and before Phase 3 (write requirements doc). The synthesis is the user's last opportunity to correct the agent's interpretation before the doc lands. It serves two purposes: synthesis confirmation (the user agreed to many individual things in dialogue but never saw the whole) and a transition checkpoint ("about to write a doc").
+
+Fires for **all tiers** including Lightweight. Skip Phase 2.5 entirely on the Phase 0.1b non-software (universal-brainstorming) route.
+
+**Headless / pipeline mode:** When invoked from a `disable-model-invocation` context (LFG, SLFG, or any automated pipeline), skip the chat-time stage entirely — there is no synchronous user to confirm with. Instead, route the internal three-bucket draft directly into the doc body sections per the "Doc shape after confirmation" table below, and route any Inferred bets to `## Assumptions` in the requirements doc so downstream review (document-review, ce-plan, human PR review) can scrutinize them explicitly. Do not present the scoping synthesis to chat; proceed directly to Phase 3 doc-write.
+
+---
+
+## Stage 1: internal three-bucket draft
+
+The internal draft is structured in three labeled buckets. Items may appear in two buckets when meaningfully both — flag the inclusion-then-exclusion as Inferred so the reasoning is captured.
+
+- **Stated** — what the user said directly (in the original prompt, prior conversation, dialogue answers, approach selection in Phase 2). Items here have explicit user-language anchors.
+- **Inferred** — what the agent assumed to fill gaps. Scope boundaries the user never explicitly named, success criteria extrapolated from intent, technical assumptions made because the brief interview didn't probe them. The Inferred bucket is the most actionable surface for correction — items here are the agent's bets.
+- **Out of scope** — deliberately excluded items. Adjacent work the agent considered but decided not to include, refactors, nice-to-haves, future-work items. Making exclusions explicit lets the agent spot anything that should actually be included.
+
+This draft is internal. Do not paste it verbatim into chat. Compose it as a thinking step, then derive stage 2 from it.
+
+---
+
+## Stage 2: the chat-time scoping synthesis
+
+The scoping synthesis is what the user actually sees. It reflects the dialogue's substance back so the user can pattern-match — long enough to serve a multi-turn conversation, short enough to be high-impact only. The reference shape is what two product collaborators would say to each other after a real discussion: "OK, so we're doing X, with Y trade-off, deferring Z, and one thing I want to double-check is W. Sound right?"
+
+The scoping synthesis has up to four named sections, each **render-conditional** on having something to say. Empty sections are omitted, not padded.
+
+1. **What we're building** (always present) — 1–3 sentences. The shape that emerged from dialogue, forward-looking, plain words. Not a transcript of "you said X."
+2. **Key trade-offs** (conditional) — 1–3 bullets, each with a brief why. Render only when real trade-offs were made in dialogue.
+3. **What's not in scope** (conditional) — 1–3 bullets, or fold into a single sentence. Render only when deferred items would surprise a downstream reader if absent.
+4. **Call outs** (conditional) — 0–3 bullets. Residual forks the dialogue didn't resolve: post-dialogue consequences (combining user answers surfaced something they couldn't see during Q&A), silent agent inferences, or — in pre-loaded contexts with no dialogue — scope bets the user is seeing for the first time. **Not "questions the agent could have asked during Phase 1.3 but didn't"** — if a call-out reads like a missed dialogue question, Phase 1.3's integration check failed; flag the gap rather than padding the section.
+
+Each section answers a different question:
+
+- **What's being built?** → shape
+- **What did we trade off?** → explicit choices made in conversation
+- **What did we cut?** → deferred items a reader would expect to see acknowledged
+- **Where might you redirect?** → residual forks: post-dialogue consequences, silent inferences, late-cycle bets
+
+Then the confirmation: *"Confirm and I'll write the requirements doc next, drawing on our dialogue and this synthesis. Or tell me what to change."* The phrasing sets the expectation that confirm → doc-write, so the user knows what's about to happen and can interrupt without ambiguity.
+
+### Path A vs Path B: the gate that fires the confirmation question
+
+Phase 2.5 has two presentation modes, gated by **two signals**: (1) did any blocking question fire before Phase 2.5? AND (2) what tier did Phase 0.3 classify the scope as? Blocking questions include Phase 0.3 scope disambiguation, Phase 1.3 collaborative dialogue probes, and Phase 2 approach selection (when a menu fires). Internal classification, Phase 1.1 scan, and Phase 1.2 pressure test are not blocking questions — they don't count.
+
+- **Path A — no blocking questions fired AND tier is Lightweight**: announce-mode. Emit "What we're building" prose only (no other sections, no confirmation question), then proceed to Phase 3 doc-write in the same turn. Do NOT end the turn waiting for acknowledgment. The user can revise after the doc lands if the shape is wrong — Lightweight Path A docs are short, post-hoc revision is cheap.
+- **Path B — at least one blocking question fired, OR tier is Standard / Deep-feature / Deep-product**: full tier-aware scoping synthesis with confirmation gate. Two scenarios fire Path B: (a) the user invested answer-time during dialogue, or (b) the user pre-loaded substantive scope content (Phase 0.2 fast-path with a richly-specified opening prompt). Either way, the substance earns a real checkpoint. The confirmation question is unconditional even when zero call-outs survive the keep test.
+
+**Why the tier guard exists.** Phase 0.2's fast path is designed for two very different cases — a tight one-line prompt that needs no dialogue ("fix the typo on line 47"), and a richly pre-loaded brainstorm context that ALSO needs no dialogue because the user pre-stated everything (e.g., handing off accumulated decisions from a prior session for a brainstorm doc backfill). Without a tier guard, both route to Path A, and the richly-loaded case gets a 1-sentence checkpoint for what may be 20+ items worth of scope. Tier-classifying Phase 0.3 distinguishes these cases — pre-loaded substance makes the tier Standard or Deep, which then routes to Path B and produces the full scoping synthesis the substance deserves. Do not simplify the gate back to a single "no questions fired" signal — that was a real defect that produced one-sentence syntheses on Deep-tier pre-loads.
+
+Path A maps to the existing "announce-mode" concept on the Phase 0.2 fast path, but only when the substance genuinely warrants 1–3 sentences. Path B is the default for every other interactive invocation.
+
+### Keep tests per section
+
+Each conditional section has its own keep test. Sections are render-conditional — an empty section is omitted, not padded with weak items.
+
+**Trade-offs keep test:** would the user be surprised if I didn't surface this acknowledgment? Real trade-offs are choices the user explicitly weighed alternatives on in dialogue, or structural choices the agent made that the user would expect to see named. Mechanical or inevitable choices (e.g., "uses the existing rule entity") fail the test and dissolve into the doc body without surfacing.
+
+**Deferred keep test:** is a reasonable downstream reader likely to ask "why isn't X here?" Items the user explicitly deferred, or items adjacent enough that a reader will look for them. Mechanical excludes (e.g., "no rate limiting because it's not in scope") fail and stay in the internal draft only.
+
+**Call-outs keep test (the affirmability test):** would the user need to read code to evaluate this? If yes, it is doc-body content — cut. If no, apply the keep test — one of the following must be true:
+
+- **Real scope fork** — another reasonable agent might choose a different scope on this dimension (who the primary actor is, whether case X is in/out, in scope vs deferred)
+- **Non-obvious scope inclusion** — a behavior the agent assumed is in scope that the user might want excluded
+- **Non-obvious scope exclusion** — an item the agent moved to deferred that the user might want in scope
+- **Cheap-now-expensive-later correction** — a scope bet that's cheap to fix now but expensive after the requirements doc lands and ce-plan consumes it
+- **Non-obvious consequence of multi-turn answers** — a downstream effect of combining user-stated answers that the user is unlikely to have tracked through dialogue. Surfaced forward-looking ("X means Y for the doc"), not retrospectively ("you said X"). This category is the multi-turn-dialogue reason call-outs exist at all in ce-brainstorm; do not filter these as "already implied by Stated"
+
+Cut anything that doesn't match a keep-test category, including:
+
+- Mechanical items where there is no real alternative
+- Implementation choices that will be settled during planning
+- Items already implied by the scoping synthesis prose
+- Re-statements of Q&A turns ("you said you wanted X") — that's transcript, not a call-out
+- Re-statements of the Phase 2 approach the user already picked
+
+### Total bullet budget across sections 2–4
+
+The cap is heuristic, not law. The real discipline is each section's keep test on each candidate. Typical bounds by tier, counting bullets across Trade-offs + Deferred + Call outs combined:
+
+| Tier | Typical total | Hard ceiling |
+|---|---|---|
+| Lightweight | 0–1 | 2 |
+| Standard | 2–4 | 5 |
+| Deep — feature | 3–5 | 7 |
+| Deep — product | 4–7 | 9 |
+
+**Above the hard ceiling, the synthesis is misshapen — do not raise the cap, re-cut at a higher level of abstraction.** Almost always, multiple bullets within a section are sub-decisions of one larger named decision. Collapse related bullets into a single one named at the level the user actually weighs in on.
+
+A useful test: read the bullets aloud. If two or more sound like "and also" extensions of the same idea, they belong as one.
+
+**Path A fires only for Lightweight tier with no blocking questions. Path B is the default for Standard, Deep-feature, and Deep-product regardless of question signal — substance earns the checkpoint, not interaction history.** Zero call-outs on Path B is normal for Lightweight, sometimes for Standard, almost never for Deep. If a Deep scoping synthesis produces zero call-outs after rich content (whether from dialogue or pre-loaded context), double-check the agent hasn't filtered consequence-class call-outs as "already implied."
+
+### Detail level: conversational, not documentary
+
+Each bullet is **1 line ideally, 2 lines maximum**. The reference shape is what two collaborators would say to each other in conversation, not what a requirements doc would say in its body. The synthesis is a forcing function for shape confirmation; the requirements doc is where the substance lives. If a bullet reads like a doc paragraph, it's wrong-shaped — the agent has compressed horizontally (fewer bullets) without compressing vertically (less per bullet), and the cap is meaningless if individual bullets bloat to fill it.
+
+Two tests:
+
+- **Read-aloud test**: would two product collaborators *say* this bullet, or would they *write* it in a spec? Say = right. Write = re-cut to a sentence or cut.
+- **Single-sentence test**: can the bullet land in one sentence? If it needs semicolons stringing clauses or a list within the bullet, it's probably two decisions sharing a bullet — split (and re-cut for count) or cut to the higher-level one.
+
+Bad vs good — detail level:
+
+| Too detailed (wrong) | Conversational (right) |
+|---|---|
+| Per-channel mute scoped to notification rules; mute applies to all events through that rule including @mentions, DMs forwarded as notifications, and bot messages; persists 24h with extension | Per-channel over per-user — support team isn't a single user |
+| Rule-delete loss path is silent and could surprise users who configured extended mutes; consider a confirmation dialog, soft-delete with state preservation, or a 7-day undo window | Rule-delete silently loses pause state — confirm no warning needed |
+
+The "What we're building" prose obeys the same discipline: 1–3 sentences describing the shape, not an enumeration of requirements. If the prose lists what's in / what's out / what's how, it has become a doc preview — cut to shape only.
+
+### Anti-patterns
+
+Each anti-pattern below produces a bullet that fails its section's keep test, or a scoping synthesis that drifts back toward the comprehensive-audit failure mode.
+
+- **Naming implementation detail in any bullet**: file paths, module names, exact JSON keys, HTTP status codes, error message wording, SQL syntax. The synthesis is scope-only; implementation is ce-plan's job. These granularity rules apply to every bullet in every section.
+- **Re-stating a Q&A turn verbatim** ("you said you wanted X"): transcript, not scoping synthesis. Reframe forward-looking ("X means Y for the doc") or cut.
+- **Re-stating the Phase 2 approach the user already picked**: the approach was chosen before Phase 2.5 — its mention belongs in one sentence of "What we're building," not as a call-out.
+- **Padding a section to meet a bullet count**: render-conditional means empty is allowed. Omit the section entirely rather than fill it with weak items.
+- **Pasting the three-bucket internal draft verbatim into chat**: that was the old shape and the volume problem it produced is why stage 2 exists. Compose internally, derive scoping synthesis sections, present compressed.
+- **Floating questions adjacent to stage 2**: if a question genuinely cannot be defaulted, pause synthesis and resolve it before presenting. Pick the question shape that matches: a blocking multiple-choice tool when options are bounded and meaningfully distinct, open-ended when option sets would unintentionally influence the user's answer. Integrate the answer, then present the scoping synthesis. Never present the scoping synthesis with adjacent floating questions — that gives the user no clear resolution path.
+
+---
+
+## Prompt templates
+
+This is directional guidance — adjust phrasing to fit dialogue context. Open-ended feedback (no `question` menu). The justification is Interaction Rule 5(a) in SKILL.md — an option menu would unintentionally influence the user's feedback toward the parts the menu lists.
+
+**Prose discipline for "What we're building" (required):** forward-looking (what *will* be in the doc), not retrospective (what's been discussed). Lead with the actual thing being built in plain words. No qualifiers ("comprehensive," "thoughtful," "substantive"). No re-stating dialogue context the user just lived through. If the work can't be said in 1–3 sentences without filler, the synthesis isn't ready yet.
+
+### Path B template (questions were asked)
+
+```
+Based on our dialogue, here's the scope I'm proposing for the requirements doc:
+
+**What we're building:** [1–3 sentences — the shape that emerged from dialogue, forward-looking, plain words]
+
+**Key trade-offs:** [render only when real trade-offs exist]
+- [explicit choice + brief why]
+- [explicit choice + brief why]
+
+**What's not in scope:** [render only when deferred items would surprise a reader]
+- [deferred item]
+- [deferred item]
+
+**Call outs:** [render only when one or more survived the keep test]
+- [scope-level fork or non-obvious consequence the user can affirm or redirect]
+- [same]
+
+Confirm and I'll write the requirements doc next, drawing on our dialogue and this synthesis. Or tell me what to change — even something I captured correctly earlier is fair game to revise (you may have changed your mind or want to correct an unstated assumption).
+```
+
+### Path A template (no questions were asked — typically Phase 0.2 short-circuit)
+
+```
+Proposing: [1–3 line shape — what the doc will say in plain words].
+
+No open decisions — writing the requirements doc now. Interrupt if the shape is wrong.
+```
+
+Proceed to Phase 3 doc-write in the same turn — do NOT end the turn waiting for an acknowledgment. The "interrupt if wrong" affordance means the user can revise after the doc lands, not before. Lightweight Path A docs are short, so post-hoc revision is cheap.
+
+### Worked example: compression from internal draft to scoping synthesis (Standard tier)
+
+For a notification-mute feature where the internal draft had 5 Stated items, 4 Inferred items, and 3 Out-of-scope items, the compressed Stage 2 looks like:
+
+```
+Based on our dialogue, here's the scope I'm proposing for the requirements doc:
+
+**What we're building:** Per-channel mute on notification rules, with a 24h preset for the support team's 3 AM ping problem. Mute lives on the rule itself and survives rule edits.
+
+**Key trade-offs:**
+- Per-channel over per-user — support team isn't a single user
+- Mute on the rule, not a separate entity — pause state survives edits
+
+**What's not in scope:**
+- Presence-based mute and quiet-hours schedules — deferred for later
+- Cross-rule mute groups — would force a rule-grouping concept we don't have
+
+**Call outs:**
+- Rule-delete silently loses pause state — confirm no warning needed
+
+Confirm and I'll write the requirements doc next, drawing on our dialogue and this synthesis. Or tell me what to change.
+```
+
+What got cut from the 12-item internal draft and why:
+
+- Stated items already covered by the "What we're building" prose dissolved silently
+- "Use existing rule entity" — mechanical, no real trade-off
+- "Use Postgres for persistence" — implementation detail (ce-plan's job), failed granularity rules
+- One Out-of-scope item ("no rate limiting") — mechanical exclude, no reader would ask about it
+- Three Inferred items rolled into the Trade-offs section as the explicit choices behind them
+
+What survived: a scoping synthesis with substance proportional to the dialogue, bounded at the Standard ceiling of 5 bullets across the three conditional sections — any more would have triggered a re-cut at higher abstraction.
+
+---
+
+## Pre-flight re-review
+
+Before emitting the scoping synthesis, re-read the draft as a user would read it. Two failure modes to catch:
+
+- **The scoping synthesis reads like a requirements-doc preview.** Prose enumerates what's in/out, bullets are documentary instead of conversational. The synthesis is a shape-confirmation checkpoint, not a doc preview — if it reads as preview, Phase 2.5 and Phase 3 have collapsed into one step. Revise to conversational shape, or accept that the requirements doc itself will contain the detail and the synthesis should be lighter.
+- **The bullet count fits the cap but each bullet is over-detailed.** Hitting 5 bullets in Standard while each bullet is a paragraph means the agent met the count cap by compressing horizontally (fewer bullets) without compressing vertically (less per bullet). The cap is meaningless if individual bullets bloat to fill it. Re-cut to sentence-level bullets.
+
+This is one mental act — re-read as the user — not a checklist to mechanically run. The forcing function is putting yourself in the user's reading shoes briefly, with explicit attention to detail level alongside the keep tests. Revise before emitting if either failure mode fires.
+
+---
+
+## Re-present after revision; write only on confirm
+
+A revision is not a confirmation. After any user revision (even a trivially-understood swap like "move deferred item X back into scope"), integrate the change, re-present the revised scoping synthesis with the change reflected, and wait for explicit confirmation before writing the doc. The loop is:
+
+1. Present scoping synthesis → user responds
+2. User confirms → write the doc
+3. User revises → integrate, re-present revised scoping synthesis, return to step 1
+
+Doc-write fires only on explicit confirm or after the soft-cut blocking question's "proceed" option (see below). The confirmation step is what makes the scoping synthesis **confirmed** rather than "agent's last proposal" — never write immediately after a revision, even when the revision is small enough that the agent feels it understood.
+
+---
+
+## Soft-cut on circularity (not iteration count)
+
+Track which scoping synthesis items the user touched per round. The soft-cut blocking question fires **only when the same item is revised twice** (or a third-round revision targets an item already revised in round two). New-item revisions across rounds proceed without limit — revising different aspects of a wrong scoping synthesis is exactly what the mechanism should support.
+
+**Identity across rounds is by decision dimension, not surface wording or section.** A revision may cause stage 2 to re-derive — the same underlying decision can come back rephrased, merged with another bullet, or moved to a different section (e.g., what was a Trade-off in round one becomes a Call-out in round two after the user pushed back). "Same item" means the same underlying decision regardless of which section currently holds it. When a re-cut collapses multiple prior bullets into one, the new combined bullet inherits the "touched" status of any of its constituents — soft-cut fires if any underlying decision was already revised once before.
+
+When the soft-cut fires, use the platform's blocking question tool (`question` in OpenCode) with two options:
+
+- `Proceed and write the requirements doc`
+- `Hold off — keep discussing before the doc`
+
+Fall back to a numbered list in chat only when no blocking tool exists or the call errors. Never silently skip.
+
+---
+
+## Self-redirect
+
+If the user response indicates they're in the wrong skill or want a different workflow (e.g., "this is too small, just ce:work it" or "this needs more thought, let me brainstorm differently"):
+
+- Stop ce-brainstorm
+- Suggest the alternative skill the user appears to want (e.g., `ce:work`, `ce:debug`)
+- Offer to load it in-session
+- Do not push back or argue — the user's redirect signal is the deliberate choice
+
+This support exists because the scoping synthesis is an honest checkpoint. If the user discovers the skill choice was wrong by reading the scoping synthesis, redirecting is the right move.
+
+---
+
+## Doc shape after confirmation
+
+After user confirmation (or after the soft-cut decision proceeds), Phase 3 writes the requirements doc. The internal draft does NOT carry into the doc as a `## Synthesis` section. Only the "What we're building" prose embeds, as `## Summary` at the top. Internal-draft content dissolves into the doc's body sections:
+
+| Internal-draft element | Where it goes in the doc |
+|---|---|
+| "What we're building" prose | `## Summary` (1–3 lines, forward-looking, what's proposed) |
+| Stated bullets | `## Requirements` (numbered R-IDs, full detail) and where relevant `## Problem Frame` for narrative context |
+| Inferred bullets | `## Key Decisions` (with rationale) — bets the user accepted in dialogue become decisions in the doc. |
+| Out-of-scope bullets | `## Scope Boundaries` |
+
+The chat-time Trade-offs section dissolves into `## Key Decisions` (the explicit choices acknowledged in chat become documented decisions). The chat-time What's-not-in-scope section dissolves into `## Scope Boundaries`.
+
+**Headless / pipeline mode:** Inferred bets route to `## Assumptions` instead of `## Key Decisions` — they were not user-confirmed in chat and should be surfaced explicitly for downstream review. See `references/requirements-capture.md` for the `## Assumptions` section contract.
+
+No italic capture-context note (e.g., "Captured at Phase 2.5..."). It would leak engineering process into an artifact whose readers do not need that signal.
+
+The doc's `## Summary` and `## Problem Frame` must serve distinct purposes — see `references/brainstorm-sections.md` "Discipline: Summary vs Problem Frame" for the rules.

package/skills/ce-brainstorm/references/universal-brainstorming.md

@@ -57,7 +57,7 @@ When the conversation has enough material to narrow — reflect back what you've
 
 **Question:** "Brainstorm wrapped. What would you like to do next?"
 
-- **Create a plan** → hand off to `/ce-plan` with the decided goal and constraints
+- **Create a plan** → hand off to `ce:plan` with the decided goal and constraints
 - **Save summary to disk** → write the summary as a markdown file in the current working directory
 - **Open in Proof (web app) — review and comment to iterate with the agent** → load the `ce-proof` skill to open the doc in Every's Proof editor, iterate with the agent via comments, or copy a link to share with others
 - **Done** → the conversation was the value, no artifact needed