Merge upstream v2.67.0 with fork customizations preserved
Brings in 79 upstream commits via merge-upstream branch. Conflicts resolved
by taking the merge-upstream version, which contains all triaged fork-vs-upstream
decisions from the upstream-merge skill workflow.
See merge commit fe3b1ee for the detailed triage breakdown of the 15 both-changed
files (7 keep deleted, 1 keep local, 1 restore from upstream, 6 merge both).
This commit is contained in:
John Lamb
@@ -14,6 +14,8 @@ The durable output of this workflow is a **requirements document**. In other wor
|
||||
|
||||
This skill does not implement code. It explores, clarifies, and documents decisions for later planning or execution.
|
||||
|
||||
**IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., `src/models/user.rb`), never absolute paths. Absolute paths break portability across machines, worktrees, and teammates.**
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Assess scope first** - Match the amount of ceremony to the size and ambiguity of the work.
|
||||
@@ -33,6 +35,7 @@ This skill does not implement code. It explores, clarifies, and documents decisi
|
||||
## Output Guidance
|
||||
|
||||
- **Keep outputs concise** - Prefer short sections, brief bullets, and only enough detail to support the next decision.
|
||||
- **Use repo-relative paths** - When referencing files, use paths relative to the repo root (e.g., `src/models/user.rb`), never absolute paths. Absolute paths make documents non-portable across machines and teammates.
|
||||
|
||||
## Feature Description
|
||||
|
||||
@@ -53,6 +56,20 @@ If the user references an existing brainstorm topic or document, or there is an
|
||||
- Confirm with the user before resuming: "Found an existing requirements doc for [topic]. Should I continue from this, or start fresh?"
|
||||
- If resuming, summarize the current state briefly, continue from its existing decisions and outstanding questions, and update the existing document instead of creating a duplicate
|
||||
|
||||
#### 0.1b Classify Task Domain
|
||||
|
||||
Before proceeding to Phase 0.2, classify whether this is a software task. The key question is: **does the task involve building, modifying, or architecting software?** -- not whether the task *mentions* software topics.
|
||||
|
||||
**Software** (continue to Phase 0.2) -- the task references code, repositories, APIs, databases, or asks to build/modify/debug/deploy software.
|
||||
|
||||
**Non-software brainstorming** (route to universal brainstorming) -- BOTH conditions must be true:
|
||||
- None of the software signals above are present
|
||||
- The task describes something the user wants to explore, decide, or think through in a non-software domain
|
||||
|
||||
**Neither** (respond directly, skip all brainstorming phases) -- the input is a quick-help request, error message, factual question, or single-step task that doesn't need a brainstorm.
|
||||
|
||||
**If non-software brainstorming is detected:** Read `references/universal-brainstorming.md` and use those facilitation principles to brainstorm with the user naturally. Do not follow the software brainstorming phases below.
|
||||
|
||||
#### 0.2 Assess Whether Brainstorming Is Needed
|
||||
|
||||
**Clear requirements indicators:**
|
||||
@@ -93,6 +110,12 @@ If nothing obvious appears after a short scan, say so and continue. Two rules go
|
||||
|
||||
2. **Defer design decisions to planning** — Implementation details like schemas, migration strategies, endpoint structure, or deployment topology belong in planning, not here — unless the brainstorm is itself about a technical or architectural decision, in which case those details are the subject of the brainstorm and should be explored.
|
||||
|
||||
**Slack context** (opt-in, Standard and Deep only) — never auto-dispatch. Route by condition:
|
||||
|
||||
- **Tools available + user asked**: Dispatch `compound-engineering:research:slack-researcher` with a brief summary of the brainstorm topic alongside Phase 1.1 work. Incorporate findings into constraint and context awareness.
|
||||
- **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
|
||||
- **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."
|
||||
|
||||
#### 1.2 Product Pressure Test
|
||||
|
||||
Before generating approaches, challenge the request to catch misframing. Match depth to scope:
|
||||
@@ -117,13 +140,10 @@ Before generating approaches, challenge the request to catch misframing. Match d
|
||||
|
||||
#### 1.3 Collaborative Dialogue
|
||||
|
||||
Use the platform's blocking question tool when available (see Interaction Rules). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
|
||||
Follow the Interaction Rules above. Use the platform's blocking question tool when available.
|
||||
|
||||
**Guidelines:**
|
||||
- Ask questions **one at a time**
|
||||
- Prefer multiple choice when natural options exist
|
||||
- Prefer **single-select** when choosing one direction, one priority, or one next step
|
||||
- Use **multi-select** only for compatible sets that can all coexist; if prioritization matters, ask which selected item is primary
|
||||
- Ask what the user is already thinking before offering your own ideas. This surfaces hidden context and prevents fixation on AI-generated framings.
|
||||
- Start broad (problem, users, value) then narrow (constraints, exclusions, edge cases)
|
||||
- Clarify the problem frame, validate assumptions, and ask about success criteria
|
||||
- Make requirements concrete enough that planning will not need to invent behavior
|
||||
@@ -137,6 +157,10 @@ Use the platform's blocking question tool when available (see Interaction Rules)
|
||||
|
||||
If multiple plausible directions remain, propose **2-3 concrete approaches** based on research and conversation. Otherwise state the recommended direction directly.
|
||||
|
||||
Use at least one non-obvious angle — inversion (what if we did the opposite?), constraint removal (what if X weren't a limitation?), or analogy from how another domain solves this. The first approaches that come to mind are usually variations on the same axis.
|
||||
|
||||
Present approaches first, then evaluate. Let the user see all options before hearing which one is recommended — leading with a recommendation before the user has seen alternatives anchors the conversation prematurely.
|
||||
|
||||
When useful, include one deliberately higher-upside alternative:
|
||||
- Identify what adjacent addition or reframing would most increase usefulness, compounding value, or durability without disproportionate carrying cost. Present it as a challenger option alongside the baseline, not as the default. Omit it when the work is already obviously over-scoped or the baseline request is clearly the right move.
|
||||
|
||||
@@ -146,7 +170,9 @@ For each approach, provide:
|
||||
- Key risks or unknowns
|
||||
- When it's best suited
|
||||
|
||||
Lead with your recommendation and explain why. Prefer simpler solutions when added complexity creates real carrying cost, but do not reject low-cost, high-value polish just because it is not strictly necessary.
|
||||
After presenting all approaches, state your recommendation and explain why. Prefer simpler solutions when added complexity creates real carrying cost, but do not reject low-cost, high-value polish just because it is not strictly necessary.
|
||||
|
||||
**Deploy wiring flag:** If any approach introduces new backend env vars or config fields, call this out explicitly in the approach description. Deploy values files (e.g. `values.yaml`, `.env.*`, Terraform vars) must be updated alongside the config code — not as a follow-up. This is a hard-won lesson; see `docs/solutions/deployment-issues/missing-env-vars-in-values-yaml.md`.
|
||||
|
||||
**Deploy wiring flag:** If any approach introduces new backend env vars or config fields, call this out explicitly in the approach description. Deploy values files (e.g. `values.yaml`, `.env.*`, Terraform vars) must be updated alongside the config code — not as a follow-up. This is a hard-won lesson; see `docs/solutions/deployment-issues/missing-env-vars-in-values-yaml.md`.
|
||||
|
||||
@@ -159,133 +185,10 @@ If relevant, call out whether the choice is:
|
||||
|
||||
### Phase 3: Capture the Requirements
|
||||
|
||||
Write or update a requirements document only when the conversation produced durable decisions worth preserving.
|
||||
|
||||
This document should behave like a lightweight PRD without PRD ceremony. Include what planning needs to execute well, and skip sections that add no value for the scope.
|
||||
|
||||
The requirements document is for product definition and scope control. Do **not** include implementation details such as libraries, schemas, endpoints, file layouts, or code structure unless the brainstorm is inherently technical and those details are themselves the subject of the decision.
|
||||
|
||||
**Required content for non-trivial work:**
|
||||
- Problem frame
|
||||
- Concrete requirements or intended behavior with stable IDs
|
||||
- Scope boundaries
|
||||
- Success criteria
|
||||
|
||||
**Include when materially useful:**
|
||||
- Key decisions and rationale
|
||||
- Dependencies or assumptions
|
||||
- Outstanding questions
|
||||
- Alternatives considered
|
||||
- High-level technical direction only when the work is inherently technical and the direction is part of the product/architecture decision
|
||||
|
||||
**Document structure:** Use this template and omit clearly inapplicable optional sections:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: YYYY-MM-DD
|
||||
topic: <kebab-case-topic>
|
||||
---
|
||||
|
||||
# <Topic Title>
|
||||
|
||||
## Problem Frame
|
||||
[Who is affected, what is changing, and why it matters]
|
||||
|
||||
## Requirements
|
||||
|
||||
**[Group Header]**
|
||||
- R1. [Concrete requirement in this group]
|
||||
- R2. [Concrete requirement in this group]
|
||||
|
||||
**[Group Header]**
|
||||
- R3. [Concrete requirement in this group]
|
||||
|
||||
## Success Criteria
|
||||
- [How we will know this solved the right problem]
|
||||
|
||||
## Scope Boundaries
|
||||
- [Deliberate non-goal or exclusion]
|
||||
|
||||
## Key Decisions
|
||||
- [Decision]: [Rationale]
|
||||
|
||||
## Dependencies / Assumptions
|
||||
- [Only include if material]
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Resolve Before Planning
|
||||
- [Affects R1][User decision] [Question that must be answered before planning can proceed]
|
||||
|
||||
### Deferred to Planning
|
||||
- [Affects R2][Technical] [Question that should be answered during planning or codebase exploration]
|
||||
- [Affects R2][Needs research] [Question that likely requires research during planning]
|
||||
|
||||
## Next Steps
|
||||
[If `Resolve Before Planning` is empty: `→ /ce:plan` for structured implementation planning]
|
||||
[If `Resolve Before Planning` is not empty: `→ Resume /ce:brainstorm` to resolve blocking questions before planning]
|
||||
```
|
||||
|
||||
**Visual communication** — Include a visual aid when the requirements would be significantly easier to understand with one. Visual aids are conditional on content patterns, not on depth classification — a Lightweight brainstorm about a complex workflow may warrant a diagram; a Deep brainstorm about a straightforward feature may not.
|
||||
|
||||
**When to include:**
|
||||
|
||||
| Requirements describe... | Visual aid | Placement |
|
||||
|---|---|---|
|
||||
| A multi-step user workflow or process | Mermaid flow diagram or ASCII flow with annotations | After Problem Frame, or under its own `## User Flow` heading for substantial flows (>10 nodes) |
|
||||
| 3+ behavioral modes, variants, or states | Markdown comparison table | Within the Requirements section |
|
||||
| 3+ interacting participants (user roles, system components, external services) | Mermaid or ASCII relationship diagram | After Problem Frame, or under its own `## Architecture` heading |
|
||||
| Multiple competing approaches being compared | Comparison table | Within Phase 2 approach exploration |
|
||||
|
||||
**When to skip:**
|
||||
- Prose already communicates the concept clearly
|
||||
- The diagram would just restate the requirements in visual form without adding comprehension value
|
||||
- The visual describes implementation architecture, data schemas, state machines, or code structure (that belongs in `ce:plan`)
|
||||
- The brainstorm is simple and linear with no multi-step flows, mode comparisons, or multi-participant interactions
|
||||
|
||||
**Format selection:**
|
||||
- **Mermaid** (default) for simple flows — 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 — CLI commands at each step, decision logic branches, file path layouts, multi-column spatial arrangements. More expressive than mermaid when the diagram's value comes from annotations within steps. Follow 80-column max for code blocks, use vertical stacking.
|
||||
- **Markdown tables** for mode/variant comparisons and approach comparisons.
|
||||
- Keep diagrams proportionate to the content. A simple 5-step workflow gets 5-10 nodes. A complex workflow with decision branches and annotations at each step may need 15-20 nodes — that is fine if every node earns its place.
|
||||
- Place inline at the point of relevance, not in a separate section.
|
||||
- Conceptual level only — user flows, information flows, mode comparisons, component responsibilities. Not implementation architecture, data schemas, or code structure.
|
||||
- Prose is authoritative: when a visual aid and surrounding prose disagree, the prose governs.
|
||||
|
||||
After generating a visual aid, verify it accurately represents the prose requirements — correct sequence, no missing branches, no merged steps. Diagrams without code to validate against carry higher inaccuracy risk than code-backed diagrams.
|
||||
|
||||
For **Standard** and **Deep** brainstorms, a requirements document is usually warranted.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
For very small requirements docs with only 1-3 simple requirements, plain bullet requirements are acceptable. For **Standard** and **Deep** requirements docs, use stable IDs like `R1`, `R2`, `R3` so planning and later review can refer to them unambiguously.
|
||||
|
||||
When requirements span multiple distinct concerns, group them under bold topic headers within the Requirements section. The trigger for grouping is distinct logical areas, not item count — even four requirements benefit from headers if they cover three different topics. Group by logical theme (e.g., "Packaging", "Migration and Compatibility", "Contributor Workflow"), not by the order they were discussed. Requirements keep their original stable IDs — numbering does not restart per group. A requirement belongs to whichever group it fits best; do not duplicate it across groups. Skip grouping only when all requirements are about the same thing.
|
||||
|
||||
When the work is simple, combine sections rather than padding them. A short requirements document is better than a bloated one.
|
||||
|
||||
Before finalizing, check:
|
||||
- What would `ce:plan` still have to invent if this brainstorm ended now?
|
||||
- Do any requirements depend on something claimed to be out of scope?
|
||||
- Are any unresolved items actually product decisions rather than planning questions?
|
||||
- Did implementation details leak in when they shouldn't have?
|
||||
- Do any requirements claim that infrastructure is absent without that claim having been verified against the codebase? If so, verify now or label as an unverified assumption.
|
||||
- Is there a low-cost change that would make this materially more useful?
|
||||
- Would a visual aid (flow diagram, comparison table, relationship diagram) help a reader grasp the requirements faster than prose alone?
|
||||
|
||||
If planning would need to invent product behavior, scope boundaries, or success criteria, the brainstorm is not complete yet.
|
||||
|
||||
Ensure `docs/brainstorms/` directory exists before writing.
|
||||
|
||||
If a document contains outstanding questions:
|
||||
- Use `Resolve Before Planning` only for questions that truly block planning
|
||||
- If `Resolve Before Planning` is non-empty, keep working those questions during the brainstorm by default
|
||||
- If the user explicitly wants to proceed anyway, convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question before proceeding
|
||||
- Do not force resolution of technical questions during brainstorming just to remove uncertainty
|
||||
- Put technical questions, or questions that require validation or research, under `Deferred to Planning` when they are better answered there
|
||||
- Use tags like `[Needs research]` when the planner should likely investigate the question rather than answer it from repo context alone
|
||||
- Carry deferred questions forward explicitly rather than treating them as a failure to finish the requirements doc
|
||||
|
||||
### Phase 3.5: Document Review
|
||||
|
||||
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.
|
||||
@@ -296,91 +199,4 @@ When document-review returns "Review complete", proceed to Phase 4.
|
||||
|
||||
### Phase 4: Handoff
|
||||
|
||||
#### 4.1 Present Next-Step Options
|
||||
|
||||
Present next steps using the platform's blocking question tool when available (see Interaction Rules). Otherwise present numbered options in chat and end the turn.
|
||||
|
||||
If `Resolve Before Planning` contains any items:
|
||||
- Ask the blocking questions now, one at a time, by default
|
||||
- If the user explicitly wants to proceed anyway, first convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question
|
||||
- If the user chooses to pause instead, present the handoff as paused or blocked rather than complete
|
||||
- Do not offer `Proceed to planning` or `Proceed directly to work` while `Resolve Before Planning` remains non-empty
|
||||
|
||||
**Question when no blocking questions remain:** "Brainstorm complete. What would you like to do next?"
|
||||
|
||||
**Question when blocking questions remain and user wants to pause:** "Brainstorm paused. Planning is blocked until the remaining questions are resolved. What would you like to do next?"
|
||||
|
||||
Present only the options that apply:
|
||||
- **Proceed to planning (Recommended)** - Run `/ce:plan` for structured implementation planning
|
||||
- **Proceed directly to work** - Only offer this when scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain
|
||||
- **Run additional document review** - Offer this only when a requirements document exists. Runs another pass for further refinement
|
||||
- **Ask more questions** - Continue clarifying scope, preferences, or edge cases
|
||||
- **Share to Proof** - Offer this only when a requirements document exists
|
||||
- **Done for now** - Return later
|
||||
|
||||
If the direct-to-work gate is not satisfied, omit that option entirely.
|
||||
|
||||
#### 4.2 Handle the Selected Option
|
||||
|
||||
**If user selects "Proceed to planning (Recommended)":**
|
||||
|
||||
Immediately run `/ce:plan` in the current session. Pass the requirements document path when one exists; otherwise pass a concise summary of the finalized brainstorm decisions. Do not print the closing summary first.
|
||||
|
||||
**If user selects "Proceed directly to work":**
|
||||
|
||||
Immediately run `/ce:work` in the current session using the finalized brainstorm output as context. If a compact requirements document exists, pass its path. Do not print the closing summary first.
|
||||
|
||||
**If user selects "Share to Proof":**
|
||||
|
||||
```bash
|
||||
CONTENT=$(cat docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md)
|
||||
TITLE="Requirements: <topic title>"
|
||||
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
|
||||
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
||||
```
|
||||
|
||||
Display the URL prominently: `View & collaborate in Proof: <PROOF_URL>`
|
||||
|
||||
If the curl fails, skip silently. Then return to the Phase 4 options.
|
||||
|
||||
**If user selects "Ask more questions":** Return to Phase 1.3 (Collaborative Dialogue) and continue asking the user questions one at a time to further refine the design. Probe deeper into edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4. Do not show the closing summary yet.
|
||||
|
||||
**If user selects "Run additional document review":**
|
||||
|
||||
Load the `document-review` skill and apply it to the requirements document for another pass.
|
||||
|
||||
When document-review returns "Review complete", return to the normal Phase 4 options and present only the options that still apply. Do not show the closing summary yet.
|
||||
|
||||
#### 4.3 Closing Summary
|
||||
|
||||
Use the closing summary only when this run of the workflow is ending or handing off, not when returning to the Phase 4 options.
|
||||
|
||||
When complete and ready for planning, display:
|
||||
|
||||
```text
|
||||
Brainstorm complete!
|
||||
|
||||
Requirements doc: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md # if one was created
|
||||
|
||||
Key decisions:
|
||||
- [Decision 1]
|
||||
- [Decision 2]
|
||||
|
||||
Recommended next step: `/ce:plan`
|
||||
```
|
||||
|
||||
If the user pauses with `Resolve Before Planning` still populated, display:
|
||||
|
||||
```text
|
||||
Brainstorm paused.
|
||||
|
||||
Requirements doc: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md # if one was created
|
||||
|
||||
Planning is blocked by:
|
||||
- [Blocking question 1]
|
||||
- [Blocking question 2]
|
||||
|
||||
Resume with `/ce:brainstorm` when ready to resolve these before planning.
|
||||
```
|
||||
Present next-step options and execute the user's selection. Read `references/handoff.md` for the option logic, dispatch instructions, and closing summary format.
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
# Handoff
|
||||
|
||||
This content is loaded when Phase 4 begins — after the requirements document is written and reviewed.
|
||||
|
||||
---
|
||||
|
||||
#### 4.1 Present Next-Step Options
|
||||
|
||||
Present the options using the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the numbered options in chat and wait for the user's reply before proceeding.
|
||||
|
||||
If `Resolve Before Planning` contains any items:
|
||||
- Ask the blocking questions now, one at a time, by default
|
||||
- If the user explicitly wants to proceed anyway, first convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question
|
||||
- If the user chooses to pause instead, present the handoff as paused or blocked rather than complete
|
||||
- Do not offer `Proceed to planning` or `Proceed directly to work` while `Resolve Before Planning` remains non-empty
|
||||
|
||||
**Question when no blocking questions remain:** "Brainstorm complete. What would you like to do next?"
|
||||
|
||||
**Question when blocking questions remain and user wants to pause:** "Brainstorm paused. Planning is blocked until the remaining questions are resolved. What would you like to do next?"
|
||||
|
||||
Present only the options that apply, keeping the total at 4 or fewer:
|
||||
|
||||
- **Proceed to planning (Recommended)** - Move to `/ce:plan` for structured implementation planning. Shown only when `Resolve Before Planning` is empty.
|
||||
- **Proceed directly to work** - Skip planning and move to `/ce:work`; suited to lightweight, well-defined changes. Shown only when `Resolve Before Planning` is empty **and** scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain (the "direct-to-work gate").
|
||||
- **Continue the brainstorm** - Answer more clarifying questions to tighten scope, edge cases, and preferences. Always shown.
|
||||
- **Open in Proof (web app) — review and comment to iterate with the agent** - Open the doc in Every's Proof editor, iterate with the agent via comments, or copy a link to share with others. Shown only when a requirements document exists **and** the direct-to-work gate is not satisfied (when both conditions collide, `Proceed directly to work` takes priority and Proof becomes reachable via free-form request).
|
||||
- **Done for now** - Pause; the requirements doc is saved and can be resumed later. Always shown.
|
||||
|
||||
**Surface additional document review contextually, not as a menu fixture:** When the prior document-review pass surfaced residual P0/P1 findings that the user has not addressed, mention them adjacent to the menu and offer another review pass in prose (e.g., "Document review flagged 2 P1 findings you may want to address — want me to run another pass?"). Do not add it to the option list.
|
||||
|
||||
#### 4.2 Handle the Selected Option
|
||||
|
||||
**If user selects "Proceed to planning (Recommended)":**
|
||||
|
||||
Immediately run `/ce:plan` in the current session. Pass the requirements document path when one exists; otherwise pass a concise summary of the finalized brainstorm decisions. Do not print the closing summary first.
|
||||
|
||||
**If user selects "Proceed directly to work":**
|
||||
|
||||
Immediately run `/ce:work` in the current session using the finalized brainstorm output as context. If a compact requirements document exists, pass its path. Do not print the closing summary first.
|
||||
|
||||
**If user selects "Continue the brainstorm":** Return to Phase 1.3 (Collaborative Dialogue) and continue asking the user clarifying questions one at a time to further refine scope, edge cases, constraints, and preferences. Continue until the user is satisfied, then return to Phase 4. Do not show the closing summary yet.
|
||||
|
||||
**If user selects "Open in Proof (web app) — review and comment to iterate with the agent":**
|
||||
|
||||
Load the `proof` skill in HITL-review mode with:
|
||||
|
||||
- **source file:** `docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md`
|
||||
- **doc title:** `Requirements: <topic title>`
|
||||
- **identity:** `ai:compound-engineering` / `Compound Engineering`
|
||||
- **recommended next step:** `/ce:plan` (shown in the proof skill's final terminal output)
|
||||
|
||||
Follow `references/hitl-review.md` in the proof skill. It uploads the doc, prompts the user for review in Proof's web UI, ingests each thread by reading it fresh and replying in-thread, applies agreed edits as tracked suggestions, and syncs the final markdown back to the source file atomically on proceed.
|
||||
|
||||
When the proof skill returns control:
|
||||
|
||||
- `status: proceeded` with `localSynced: true` → the requirements doc on disk now reflects the review. Return to the Phase 4 options and re-render the menu (the doc may have changed substantially during review, so option eligibility can shift — re-evaluate `Resolve Before Planning`, direct-to-work gate, and residual document-review findings against the updated doc).
|
||||
- `status: proceeded` with `localSynced: false` → the reviewed version lives in Proof at `docUrl` but the local copy is stale. Offer to pull the Proof doc to `localPath` using the proof skill's Pull workflow. Re-render the Phase 4 menu after the pull completes (or is declined). If the pull was declined, include a one-line note above the menu that `<localPath>` is stale vs. Proof — otherwise `Proceed to planning` / `Proceed directly to work` will silently read the pre-review copy.
|
||||
- `status: done_for_now` → the doc on disk may be stale if the user edited in Proof before leaving. Offer to pull the Proof doc to `localPath` so the local requirements file stays in sync, then return to the Phase 4 options. If the pull was declined, include the stale-local note above the menu. `done_for_now` means the user stopped the HITL loop without syncing — it does not mean they ended the whole brainstorm; they may still want to proceed to planning or continue the brainstorm.
|
||||
- `status: aborted` → fall back to the Phase 4 options without changes.
|
||||
|
||||
If the initial upload fails (network error, Proof API down), retry once after a short wait. If it still fails, tell the user the upload didn't succeed and briefly explain why, then return to the Phase 4 options — don't leave them wondering why the option did nothing.
|
||||
|
||||
**If the user asks to run another document review** (either from the contextual prompt when P0/P1 findings remain, or by free-form request):
|
||||
|
||||
Load the `document-review` skill and apply it to the requirements document for another pass. When document-review returns "Review complete", return to the normal Phase 4 options and present only the options that still apply. Do not show the closing summary yet.
|
||||
|
||||
**If user selects "Done for now":** Display the closing summary (see 4.3) and end the turn.
|
||||
|
||||
#### 4.3 Closing Summary
|
||||
|
||||
Use the closing summary only when this run of the workflow is ending or handing off, not when returning to the Phase 4 options.
|
||||
|
||||
When complete and ready for planning, display:
|
||||
|
||||
```text
|
||||
Brainstorm complete!
|
||||
|
||||
Requirements doc: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md # if one was created
|
||||
|
||||
Key decisions:
|
||||
- [Decision 1]
|
||||
- [Decision 2]
|
||||
|
||||
Recommended next step: `/ce:plan`
|
||||
```
|
||||
|
||||
If the user pauses with `Resolve Before Planning` still populated, display:
|
||||
|
||||
```text
|
||||
Brainstorm paused.
|
||||
|
||||
Requirements doc: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md # if one was created
|
||||
|
||||
Planning is blocked by:
|
||||
- [Blocking question 1]
|
||||
- [Blocking question 2]
|
||||
|
||||
Resume with `/ce:brainstorm` when ready to resolve these before planning.
|
||||
```
|
||||
@@ -0,0 +1,104 @@
|
||||
# Requirements Capture
|
||||
|
||||
This content is loaded when Phase 3 begins — after the collaborative dialogue (Phases 0-2) has produced durable decisions worth preserving.
|
||||
|
||||
---
|
||||
|
||||
This document should behave like a lightweight PRD without PRD ceremony. Include what planning needs to execute well, and skip sections that add no value for the scope.
|
||||
|
||||
The requirements document is for product definition and scope control. Do **not** include implementation details such as libraries, schemas, endpoints, file layouts, or code structure unless the brainstorm is inherently technical and those details are themselves the subject of the decision.
|
||||
|
||||
**Required content for non-trivial work:**
|
||||
- Problem frame
|
||||
- Concrete requirements or intended behavior with stable IDs
|
||||
- Scope boundaries
|
||||
- Success criteria
|
||||
|
||||
**Include when materially useful:**
|
||||
- Key decisions and rationale
|
||||
- Dependencies or assumptions
|
||||
- Outstanding questions
|
||||
- Alternatives considered
|
||||
- High-level technical direction only when the work is inherently technical and the direction is part of the product/architecture decision
|
||||
|
||||
**Document structure:** Use this template and omit clearly inapplicable optional sections:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: YYYY-MM-DD
|
||||
topic: <kebab-case-topic>
|
||||
---
|
||||
|
||||
# <Topic Title>
|
||||
|
||||
## Problem Frame
|
||||
[Who is affected, what is changing, and why it matters]
|
||||
|
||||
## Requirements
|
||||
|
||||
**[Group Header]**
|
||||
- R1. [Concrete requirement in this group]
|
||||
- R2. [Concrete requirement in this group]
|
||||
|
||||
**[Group Header]**
|
||||
- R3. [Concrete requirement in this group]
|
||||
|
||||
## Success Criteria
|
||||
- [How we will know this solved the right problem]
|
||||
|
||||
## Scope Boundaries
|
||||
- [Deliberate non-goal or exclusion]
|
||||
|
||||
## Key Decisions
|
||||
- [Decision]: [Rationale]
|
||||
|
||||
## Dependencies / Assumptions
|
||||
- [Only include if material]
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Resolve Before Planning
|
||||
- [Affects R1][User decision] [Question that must be answered before planning can proceed]
|
||||
|
||||
### Deferred to Planning
|
||||
- [Affects R2][Technical] [Question that should be answered during planning or codebase exploration]
|
||||
- [Affects R2][Needs research] [Question that likely requires research during planning]
|
||||
|
||||
## Next Steps
|
||||
[If `Resolve Before Planning` is empty: `-> /ce:plan` for structured implementation planning]
|
||||
[If `Resolve Before Planning` is not empty: `-> Resume /ce:brainstorm` to resolve blocking questions before planning]
|
||||
```
|
||||
|
||||
**Visual communication** — Include a visual aid when the requirements would be significantly easier to understand with one. Read `references/visual-communication.md` for the decision criteria, format selection, and placement rules.
|
||||
|
||||
For **Standard** and **Deep** brainstorms, a requirements document is usually warranted.
|
||||
|
||||
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.
|
||||
|
||||
For very small requirements docs with only 1-3 simple requirements, plain bullet requirements are acceptable. For **Standard** and **Deep** requirements docs, use stable IDs like `R1`, `R2`, `R3` so planning and later review can refer to them unambiguously.
|
||||
|
||||
When requirements span multiple distinct concerns, group them under bold topic headers within the Requirements section. The trigger for grouping is distinct logical areas, not item count — even four requirements benefit from headers if they cover three different topics. Group by logical theme (e.g., "Packaging", "Migration and Compatibility", "Contributor Workflow"), not by the order they were discussed. Requirements keep their original stable IDs — numbering does not restart per group. A requirement belongs to whichever group it fits best; do not duplicate it across groups. Skip grouping only when all requirements are about the same thing.
|
||||
|
||||
When the work is simple, combine sections rather than padding them. A short requirements document is better than a bloated one.
|
||||
|
||||
Before finalizing, check:
|
||||
- What would `ce:plan` still have to invent if this brainstorm ended now?
|
||||
- Do any requirements depend on something claimed to be out of scope?
|
||||
- Are any unresolved items actually product decisions rather than planning questions?
|
||||
- Did implementation details leak in when they shouldn't have?
|
||||
- Do any requirements claim that infrastructure is absent without that claim having been verified against the codebase? If so, verify now or label as an unverified assumption.
|
||||
- Is there a low-cost change that would make this materially more useful?
|
||||
- Would a visual aid (flow diagram, comparison table, relationship diagram) help a reader grasp the requirements faster than prose alone?
|
||||
|
||||
If planning would need to invent product behavior, scope boundaries, or success criteria, the brainstorm is not complete yet.
|
||||
|
||||
Ensure `docs/brainstorms/` directory exists before writing.
|
||||
|
||||
If a document contains outstanding questions:
|
||||
- Use `Resolve Before Planning` only for questions that truly block planning
|
||||
- If `Resolve Before Planning` is non-empty, keep working those questions during the brainstorm by default
|
||||
- If the user explicitly wants to proceed anyway, convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question before proceeding
|
||||
- Do not force resolution of technical questions during brainstorming just to remove uncertainty
|
||||
- Put technical questions, or questions that require validation or research, under `Deferred to Planning` when they are better answered there
|
||||
- Use tags like `[Needs research]` when the planner should likely investigate the question rather than answer it from repo context alone
|
||||
- Carry deferred questions forward explicitly rather than treating them as a failure to finish the requirements doc
|
||||
@@ -0,0 +1,55 @@
|
||||
# Universal Brainstorming Facilitator
|
||||
|
||||
This file is loaded when ce:brainstorm detects a non-software task (Phase 0). It replaces the software-specific brainstorming phases with facilitation principles for any domain. Do not follow the software brainstorming workflow (Phases 0.2 through 4). Instead, absorb these principles and facilitate the brainstorm naturally.
|
||||
|
||||
---
|
||||
|
||||
## Your role
|
||||
|
||||
Be a thinking partner, not an answer machine. The user came here because they're stuck or exploring — they want to think WITH someone, not receive a deliverable. Resist the urge to generate a complete solution immediately. A premature answer anchors the conversation and kills exploration.
|
||||
|
||||
**Match the tone to the stakes.** For personal or life decisions (career changes, housing, relationships, family), lead with values and feelings before frameworks and analysis. Ask what matters to them, not just what the options are. For lighter or creative tasks (podcast topics, event ideas, side projects), energy and enthusiasm are more useful than caution.
|
||||
|
||||
## How to start
|
||||
|
||||
**Assess scope first.** Not every brainstorm needs deep exploration:
|
||||
- **Quick** (user has a clear goal, just needs a sounding board): Confirm understanding, offer a few targeted suggestions or reactions, done in 2-3 exchanges.
|
||||
- **Standard** (some unknowns, needs to explore options): 4-6 exchanges, generate and compare options, help decide.
|
||||
- **Full** (vague goal, lots of uncertainty, or high-stakes decision): Deep exploration, many exchanges, structured convergence.
|
||||
|
||||
**Ask what they're already thinking.** Before offering ideas, find out what the user has considered, tried, or rejected. This prevents fixation on AI-generated ideas and surfaces hidden constraints.
|
||||
|
||||
**When the user represents a group** (couple, family, team) — surface whose preferences are in play and where they diverge. The brainstorm shifts from "help you decide" to "help you find alignment." Ask about each person's priorities, not just the speaker's.
|
||||
|
||||
**Understand before generating.** Spend time on the problem before jumping to solutions. "What would success look like?" and "What have you already ruled out?" reveal more than "Here are 10 ideas."
|
||||
|
||||
## How to explore and generate
|
||||
|
||||
**Use diverse angles to avoid repetitive ideas.** When generating options, vary your approach across exchanges:
|
||||
- Inversion: "What if you did the opposite of the obvious choice?"
|
||||
- Constraints as creative tools: "What if budget/time/distance were no issue?" then "What if you had to do it for free?"
|
||||
- Analogy: "How does someone in a completely different context solve a similar problem?"
|
||||
- What the user hasn't considered: introduce lateral ideas from unexpected directions
|
||||
|
||||
**Separate generation from evaluation.** When exploring options, don't critique them in the same breath. Generate first, evaluate later. Make the transition explicit when it's time to narrow.
|
||||
|
||||
**Offer options to react to when the user is stuck.** People who can't generate from scratch can often evaluate presented options. Use multi-select questions to gather preferences efficiently. Always include a skip option for users who want to move faster.
|
||||
|
||||
**Keep presented options to 3-5 at any decision point.** More causes analysis paralysis.
|
||||
|
||||
## How to converge
|
||||
|
||||
When the conversation has enough material to narrow — reflect back what you've heard. Name the user's priorities as they've emerged through the conversation (what excited them, what they rejected, what they asked about). Propose a frontrunner with reasoning tied to their criteria, and invite pushback. Keep final options to 3-5 max. Don't force a final decision if the user isn't there yet — clarity on direction is a valid outcome.
|
||||
|
||||
## When to wrap up
|
||||
|
||||
**Always synthesize a summary in the chat.** Before offering any next steps, reflect back what emerged: key decisions, the direction chosen, open threads, and any assumptions made. This is the primary output of the brainstorm — the user should be able to read the summary and know what they landed on.
|
||||
|
||||
**Then offer next steps** using the platform's question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the numbered options in chat and wait for the user's reply before proceeding.
|
||||
|
||||
**Question:** "Brainstorm wrapped. What would you like to do next?"
|
||||
|
||||
- **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 `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
|
||||
@@ -0,0 +1,29 @@
|
||||
# Visual Communication in Requirements Documents
|
||||
|
||||
Visual aids are conditional on content patterns, not on depth classification — a Lightweight brainstorm about a complex workflow may warrant a diagram; a Deep brainstorm about a straightforward feature may not.
|
||||
|
||||
**When to include:**
|
||||
|
||||
| Requirements describe... | Visual aid | Placement |
|
||||
|---|---|---|
|
||||
| A multi-step user workflow or process | Mermaid flow diagram or ASCII flow with annotations | After Problem Frame, or under its own `## User Flow` heading for substantial flows (>10 nodes) |
|
||||
| 3+ behavioral modes, variants, or states | Markdown comparison table | Within the Requirements section |
|
||||
| 3+ interacting participants (user roles, system components, external services) | Mermaid or ASCII relationship diagram | After Problem Frame, or under its own `## Architecture` heading |
|
||||
| Multiple competing approaches being compared | Comparison table | Within Phase 2 approach exploration |
|
||||
|
||||
**When to skip:**
|
||||
- Prose already communicates the concept clearly
|
||||
- The diagram would just restate the requirements in visual form without adding comprehension value
|
||||
- The visual describes implementation architecture, data schemas, state machines, or code structure (that belongs in `ce:plan`)
|
||||
- The brainstorm is simple and linear with no multi-step flows, mode comparisons, or multi-participant interactions
|
||||
|
||||
**Format selection:**
|
||||
- **Mermaid** (default) for simple flows — 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 — CLI commands at each step, decision logic branches, file path layouts, multi-column spatial arrangements. More expressive than mermaid when the diagram's value comes from annotations within steps. Follow 80-column max for code blocks, use vertical stacking.
|
||||
- **Markdown tables** for mode/variant comparisons and approach comparisons.
|
||||
- Keep diagrams proportionate to the content. A simple 5-step workflow gets 5-10 nodes. A complex workflow with decision branches and annotations at each step may need 15-20 nodes — that is fine if every node earns its place.
|
||||
- Place inline at the point of relevance, not in a separate section.
|
||||
- Conceptual level only — user flows, information flows, mode comparisons, component responsibilities. Not implementation architecture, data schemas, or code structure.
|
||||
- Prose is authoritative: when a visual aid and surrounding prose disagree, the prose governs.
|
||||
|
||||
After generating a visual aid, verify it accurately represents the prose requirements — correct sequence, no missing branches, no merged steps. Diagrams without code to validate against carry higher inaccuracy risk than code-backed diagrams.
|
||||
Reference in New Issue
Block a user