@fro.bot/systematic 2.25.0 → 2.27.0

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

package/skills/ce-brainstorm/references/visual-communication.md

@@ -0,0 +1,29 @@
+# Visual Communication in Requirements Documents
+
+Visual aids are conditional on content patterns, not on document depth classification — a Lightweight requirements doc about a complex multi-surface feature may warrant a diagram; a Deep doc about a straightforward change may not.
+
+**When to include:**
+
+| Requirements describe... | Visual aid | Placement |
+|---|---|---|
+| 4+ requirements with non-linear relationships (dependencies, groupings, fan-in/fan-out) | Mermaid dependency or grouping diagram | Before or after the Requirements heading |
+| 3+ interacting system surfaces or cross-layer effects | Mermaid interaction or component diagram | Within the relevant section |
+| 3+ behavioral modes, states, or variants being compared | Markdown comparison table | Within the relevant section |
+| 3+ alternatives or trade-offs under consideration | Markdown comparison table | Within the relevant section |
+
+**When to skip:**
+- The requirements are 3 or fewer items in a straightforward list — prose bullets are sufficient
+- Prose already communicates the relationships clearly
+- The visual would duplicate what surrounding prose already shows
+- The visual describes code-level detail (specific method names, SQL columns, API field lists)
+
+**Format selection:**
+- **Mermaid** (default) for dependency graphs and interaction diagrams — 5–15 nodes, no in-box annotations, standard flowchart shapes. Use `TB` (top-to-bottom) direction so diagrams stay narrow in both rendered and source form. Source should be readable as fallback in diff views and terminals.
+- **ASCII/box-drawing diagrams** for annotated flows that need rich in-box content — decision logic branches, multi-column spatial arrangements. More expressive than mermaid when the diagram's value comes from annotations within nodes. Follow 80-column max for code blocks, use vertical stacking.
+- **Markdown tables** for mode/variant comparisons and alternative comparisons.
+- Keep diagrams proportionate to the document. A simple 4-requirement grouping gets a simple diagram. A complex dependency graph with fan-out and fan-in may need 10–15 nodes — that is fine if every node earns its place.
+- Place inline at the point of relevance, not in a separate section.
+- Requirements-structure level only — groupings, surface interactions, mode comparisons. Not implementation architecture, data schemas, or code structure.
+- Prose is authoritative: when a visual aid and its surrounding prose disagree, the prose governs.
+
+After generating a visual aid, verify it accurately represents the requirements it illustrates — correct relationships, no missing surfaces, no merged requirements.

package/skills/ce-plan/SKILL.md

@@ -165,6 +165,55 @@ Classify the work into one of these plan depths:
 
 If depth is unclear, ask one targeted question and then continue.
 
+#### 0.7 Solo-Mode Scoping Synthesis
+
+Surface call-outs to the user — the specific forks in scope or approach where user input materially changes the plan — so scope can be corrected **before Phase 1 research is spent**. Sub-agent dispatch (systematic:research:repo-research-analyst, systematic:research:learnings-researcher, etc.) is the expensive next step this phase guards against wasted effort on.
+
+Fires **only in solo invocation** — when Phase 0.2 found no upstream brainstorm doc AND Phase 0.4 stayed in ce:plan (did not route to ce:debug, ce:work, or universal-planning) AND Phase 0.5 cleared (no unresolved blockers) AND not on Phase 0.1 fast paths (resume normal, deepen-intent). Each guard is an explicit conditional. Skip Phase 0.7 entirely when any guard fails — brainstorm-sourced invocations defer to Phase 5.1.5 instead.
+
+**Read `references/synthesis-summary.md` before composing the scoping synthesis.** It carries the affirmability test, keep-test criteria, detail test, summary shape budgets, granularity rules, anti-patterns, revision-vs-confirmation discipline, doc-shape routing, soft-cut behavior, self-redirect support, the worked PII compression example, and full headless-mode routing — all required for a well-shaped synthesis.
+
+**Required gate output — do not skip; silent proceeding is not allowed.** Compose an internal three-bucket scope draft (Stated / Inferred / Out of scope — internal thinking that feeds plan-body routing at Phase 5.2, not the chat output below). Derive call-outs (specific forks where user input materially changes the plan), then emit one of the two literal templates below in chat before continuing to Phase 1.
+
+**Synthesis is pre-plan-write.** The agent does NOT yet know how plan-write will sequence the work. Do not claim PR count ("one PR"), commit/branch shape, effort or time estimates, Implementation Unit boundaries, or exact file paths in the synthesis. The synthesis surfaces decisions knowable at THIS point — for the solo variant, that's the user's request plus the Phase 0.4 bootstrap dialogue plus the agent's own internal three-bucket draft. Phase 1 research has not happened yet and there is no upstream brainstorm; do not claim grounding from either. Plan-write produces the rest. This rule holds even when the agent has formed plan-write opinions earlier in the session — those stay internal until plan-write.
+
+**Summary shape:** the summary is a **scope claim** — what the plan will target, what it will not — at affirm-or-redirect level. NOT an enumeration of Implementation Units. Form is prose, bullets, or mix; tier budgets are **ceilings, not targets** (Lightweight 1-3 lines; Standard up to 3-5 lines or 2-4 bullets; Deep up to 4-6 lines or 3-6 bullets). 1-2 lines per bullet, conversational not documentary. Less is correct when there isn't more to say. See `references/synthesis-summary.md` for keep test, detail test, and source-vocabulary discipline.
+
+**Do NOT enumerate the touch surface.** Sentences like "The touch surface is...", "This plan touches...", "The implementation reaches into..." are plan-pitch leaks. File paths, module names, directory introductions, and per-file change descriptions belong in the plan body (Implementation Units at Phase 5.2), not the synthesis. The synthesis names *what* the plan targets, not *where* the code lives.
+
+**Pre-emit scans.** Before emitting the synthesis, scan the output:
+- Bare ID references (`AE\d+`, `R\d+`, `F\d+`, `A\d+`, `U\d+`) → replace with plain names.
+- File paths (`path/like.md`, `path/like.py`, etc.) → cut unless the path IS the topic of an explicit fork in the call-outs.
+
+**Tier guard on auto-proceed:** the auto-proceed path (announce without waiting for confirmation) fires only when plan depth is **Lightweight AND zero call-outs survive**. Standard and Deep plans always fire the confirmation gate, even with zero call-outs — substance earns the checkpoint, not interaction history.
+
+**Confirmation template (Standard/Deep regardless of call-out count, or any tier with one or more call-outs surviving):**
+
+````text
+Based on your request and our brief discussion, here's the scope I'm proposing to plan against:
+
+[scope claim — what the plan will target, what it will not; affirm-or-redirect level; NOT an enumeration of Implementation Units]
+
+**Call outs:** (omit this header when zero forks survived the keep test)
+- [decision-level fork in 1-2 lines: name the choice and optional one-clause trade-off in parens. NO multi-sentence rationale, NO "my default is X" pitch]
+
+Confirm and I'll proceed to research, drawing on this scope. (You can also redirect to ce:brainstorm if this is bigger than you initially thought — I'll stop here and load it for you.)
+````
+
+Wait for user confirmation before continuing to Phase 1.
+
+**Auto-proceed template (Lightweight with zero call-outs only):**
+
+````text
+Planning: [1-3 line scope claim]
+
+No open decisions to weigh in on — proceeding to research. Interrupt if I have the scope wrong.
+````
+
+Then continue to Phase 1 without a blocking question.
+
+**Headless mode**: internal draft is composed but stage 2 (chat-time call-outs) is skipped — no synchronous user to confirm to. Continue to Phase 1 research as normal. At plan-write time (Phase 5.2), Inferred bets from the internal draft route to a `## Assumptions` section in the plan instead of Key Technical Decisions. See `references/synthesis-summary.md` Headless mode for the full routing.
+
 ### Phase 1: Gather Context
 
 #### 1.1 Local Research (Always Runs)
@@ -406,6 +455,12 @@ Examples:
 - Runtime behavior that depends on seeing actual test failures
 - Refactors that may become unnecessary once implementation starts
 
+#### 3.7 Anti-Expansion: Tangential Cleanup and Scope Creep Go to Deferred
+
+Distinct from 3.6 (which is about *unknowns* at plan time): 3.7 is about *known but tangential* work that the agent notices while planning but that falls outside the user's confirmed scope. When research surfaces an adjacent refactor, a "while we're here" cleanup, or a scope-adjacent nice-to-have ("we could also add rate limiting"), route it to the existing `### Deferred to Separate Tasks` subsection in Scope Boundaries (see Core Plan Template), not into active Implementation Units.
+
+This reinforces the synthesis discipline established at Phase 0.7 / Phase 5.1.5 — the user's confirmed scope is what the active plan executes; everything else is deferred. Does NOT impose architectural bias on extend-vs-invent decisions within confirmed scope — that judgment stays with the agent (and is surfaced via the Phase 5.1.5 synthesis when material). The user's explicit ask overrides this default — if the user explicitly requested a refactor, it's in-scope, not deferred.
+
 ### Phase 4: Write the Plan
 
 Use one planning philosophy across all depths. Change the amount of detail, not the boundary between planning and execution.
@@ -636,6 +691,19 @@ For larger `Deep` plans, extend the core template only when useful with sections
 - Do not expand implementation units into micro-step `RED/GREEN/REFACTOR` instructions
 - Do not pretend an execution-time question is settled just to make the plan look complete
 
+#### 4.3b Section Contract and Rendering
+
+Compose the plan using two paired references:
+
+- `references/plan-sections.md` — the section contract. Describes what the plan contains: the outcome the plan must enable for downstream consumers, the hard floor (Summary, Problem Frame, Requirements, KTDs, Implementation Units), the include-when-material catalog (HTD, Scope Boundaries, Open Questions, System-Wide Impact, Risks & Dependencies, Acceptance Examples, Documentation/Operational Notes, Sources & Research), the agency-driven escape hatch (introduce new sections when content warrants), and the ID/content rules.
+- `references/markdown-rendering.md` — how to present the sections in markdown (table-vs-prose by content shape, ID prefix format, diagram rendering, etc.).
+
+The section catalog is the same regardless of plan depth. Format-specific principles live in the rendering reference. The Core Plan Template above (Section 4.2) is the canonical content authority — `plan-sections.md` is a rendering/ordering layer that describes how sections present, not which sections exist.
+
+Omit "include when material" sections that don't carry information for this specific plan. Filling a section with placeholder prose is worse than omitting it.
+
+**Write tight.** A section being material is not license to pad it. Hold every kept section to the prose-economy discipline in `references/plan-sections.md`: one idea per sentence, a requirement or unit is intent plus at most one qualifier, defer forks to Open Questions rather than specifying both arms, resolve superseded text in place rather than stacking strata. Before declaring the plan written, run the named test there — could the implementer find a contradiction in each section in one pass?
+
 #### 4.4 Visual Communication in Plan Documents
 
 When the plan contains 4+ implementation units with non-linear dependencies, 3+ interacting surfaces in System-Wide Impact, 3+ behavioral modes/variants in Overview or Problem Frame, or 3+ interacting decisions in Key Technical Decisions or alternatives in Alternative Approaches, read `references/visual-communication.md` for diagram and table guidance. This covers plan-structure visuals (dependency graphs, interaction diagrams, comparison tables) — not solution-design diagrams, which are covered in Section 3.4.
@@ -666,6 +734,58 @@ If the plan originated from a requirements document, re-read that document and v
 - Blocking questions were either resolved, explicitly assumed, or sent back to `ce:brainstorm`
 - Every section of the origin document is addressed in the plan — scan each section to confirm nothing was silently dropped
 
+#### 5.1.5 Brainstorm-Sourced Scoping Synthesis
+
+Surface plan-time call-outs to the user before Phase 5.2 commits the plan to disk — the latest cheap moment to catch plan-time scope errors. The brainstorm already validated WHAT to build; this phase surfaces HOW the plan will execute on the forks that matter.
+
+Fires **only when the plan was sourced from an upstream brainstorm doc** (Phase 0.2 found a `*-requirements.md` match) AND not on Phase 0.1 fast paths (resume normal, deepen-intent). Skip Phase 5.1.5 in solo invocation — solo plans handled their synthesis in Phase 0.7.
+
+**Read `references/synthesis-summary.md` before composing the scoping synthesis.** It carries the affirmability test, keep-test criteria, detail test, summary shape budgets, granularity rules, anti-patterns, revision-vs-confirmation discipline, doc-body reading rules, doc-shape routing, soft-cut behavior, self-redirect support, the worked PII compression example, and full headless-mode routing — all required for a well-shaped synthesis.
+
+**Required gate output — do not skip; silent proceeding is not allowed.** Compose an internal three-bucket scope draft (Stated / Inferred / Out of scope — internal thinking that feeds plan-body routing at Phase 5.2, not the chat output below). Derive call-outs (specific forks where user input materially changes the plan), then emit one of the two literal templates below in chat before continuing to Phase 5.2.
+
+**Synthesis is pre-plan-write.** The agent does NOT yet know how plan-write will sequence the work. Do not claim PR count ("one PR"), commit/branch shape, effort or time estimates, Implementation Unit boundaries, or exact file paths in the synthesis. The synthesis surfaces decisions knowable at THIS point (brainstorm + research + agent posture); plan-write produces the rest. This rule holds even when the agent has formed plan-write opinions earlier in the session — those stay internal until plan-write.
+
+**Summary shape: two paragraphs.**
+
+1. **Brainstorm-scope restatement** (1-2 sentences, prose). Restates the brainstorm's scope as orientation, in the brainstorm's own vocabulary. NOT an enumeration of Implementation Units, restated constraints, or listed acceptance examples — the user wrote those.
+2. **Plan-specific scoping decisions** (prose, or bullets when multi-faceted). Scope-level commitments the agent made that the brainstorm did not: full brainstorm coverage vs. narrowed subset; adjacent refactors pulled in vs. held out; test scope at scenario level. Each item must be affirmable by the user without reading code. Form follows substance; tier budgets are **ceilings, not targets** (Lightweight 1-3 lines; Standard up to 3-5 lines or 2-4 bullets; Deep up to 4-6 lines or 3-6 bullets). 1-2 lines per bullet. Less is correct when there isn't more to say. See `references/synthesis-summary.md` for keep test, detail test, and source-vocabulary discipline.
+
+**Do NOT enumerate the touch surface.** Sentences like "The touch surface is...", "This plan touches...", "The implementation reaches into...", "Files modified include..." are plan-pitch leaks. File paths, module names, directory introductions, and per-file change descriptions belong in the plan body (Implementation Units at Phase 5.2), not the synthesis. The synthesis names *what* the plan targets, not *where* the code lives.
+
+**Pre-emit scans.** Before emitting the synthesis, scan the output:
+- Bare ID references (`AE\d+`, `R\d+`, `F\d+`, `A\d+`, `U\d+`) → replace with plain names.
+- File paths (`path/like.md`, `path/like.py`, etc.) → cut unless the path IS the topic of an explicit fork in the call-outs.
+
+**Tier guard on auto-proceed:** the auto-proceed path (announce without waiting for confirmation) fires only when plan depth is **Lightweight AND zero call-outs survive**. Standard and Deep plans always fire the confirmation gate, even with zero call-outs — substance earns the checkpoint, not interaction history.
+
+**Confirmation template (Standard/Deep regardless of call-out count, or any tier with one or more call-outs surviving):**
+
+````text
+The brainstorm scopes [1-2 sentence restatement in the brainstorm's vocabulary as orientation; NOT an enumeration of Implementation Units, constraints, or acceptance examples].
+
+This plan [plan-specific scoping decisions: full-brainstorm coverage vs. narrowed subset; adjacent refactors in or out; test scope at scenario level. NOT PR count, sequencing, IU lists, or file paths].
+
+**Call outs:** (omit this header when zero forks survived the keep test)
+- [plan-time fork in 1-2 lines: name the choice and optional one-clause trade-off in parens. NO multi-sentence rationale, NO "my default is X" pitch]
+
+Confirm and I'll write the plan next, drawing on the brainstorm, research, and this synthesis.
+````
+
+Wait for user confirmation before continuing to Phase 5.2.
+
+**Auto-proceed template (Lightweight with zero call-outs only):**
+
+````text
+Planning [brief brainstorm-scope restatement] — [plan-specific shape in one clause].
+
+No open decisions to weigh in on — proceeding to plan-write. Interrupt if I have the scope wrong.
+````
+
+Then continue to Phase 5.2 without a blocking question.
+
+**Headless mode**: internal draft is composed but stage 2 (chat-time call-outs) is skipped — no synchronous user to confirm to. Proceed to Phase 5.2 plan-write. Inferred bets from the internal draft route to a `## Assumptions` section in the plan instead of Key Technical Decisions. See `references/synthesis-summary.md` Headless mode for the full routing.
+
 #### 5.2 Write Plan File
 
 **REQUIRED: Write the plan file to disk before presenting any options.**