brainstorming

Preamble (run first)

# === RKstack Preamble (brainstorming) ===

# Read detection cache (written by session-start via rkstack detect)
if [ -f .rkstack/settings.json ]; then
  cat .rkstack/settings.json
else
  echo "WARNING: .rkstack/settings.json not found — detection cache missing"
fi

# Session-volatile checks (can change mid-session)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
_HAS_CLAUDE_MD=$([ -f CLAUDE.md ] && echo "yes" || echo "no")
echo "BRANCH: $_BRANCH"
echo "CLAUDE_MD: $_HAS_CLAUDE_MD"

Use the detection cache and preamble output to adapt your behavior:

• TypeScript/JavaScript — see detection.flowType (web or default). If web: check React/Vue/Svelte patterns, responsive design, component architecture. If default: CLI tools, MCP servers, backend scripts.
• Python — backend/ML/scripts. Check PEP8 conventions, pytest for testing.
• Go — backend/infra. Check error handling patterns, go test.
• Rust — systems. Check ownership patterns, cargo test.
• Java/C# — enterprise. Check build tool (Maven/Gradle/.NET), framework conventions.
• Ruby — web/scripting. Check Gemfile, Rails conventions if present.
• Terraform/HCL — infrastructure as code. Plan before apply, extra caution with state.
• Ansible — configuration management. Check inventory, role conventions, vault usage.
• Docker/Compose — containerized. Check service dependencies, .env patterns.
• justfile — task runner present. Use just commands instead of raw shell.
• mise — tool version manager. Versions are pinned — don't suggest global installs.
• CLAUDE.md exists — read it for project-specific commands and conventions.
• Read detection.stack for what's in the project and detection.stats for scale (files, code, complexity).
• Read detection.repoMode for solo vs collaborative.
• Read detection.services for Supabase and other service integrations.

AskUserQuestion Format

ALWAYS follow this structure for every AskUserQuestion call:

1. Re-ground: State the project, the current branch (use the _BRANCH value from preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
2. Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
3. Recommend: RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work.
4. Options: Lettered options: A) ... B) ... C) ... — when an option involves effort, show both scales: (human: ~X / CC: ~Y)

Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.

Completeness Principle

AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with AI. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans.

Effort reference — always show both scales:

Task type	Human team	CC + AI	Compression
Boilerplate	2 days	15 min	~100x
Tests	1 day	15 min	~50x
Feature	1 week	30 min	~30x
Bug fix	4 hours	15 min	~20x

Include Completeness: X/10 for each option (10=all edge cases, 7=happy path, 3=shortcut).

Completion Status

When completing a skill workflow, report status using one of:

• DONE — All steps completed successfully. Evidence provided for each claim.
• DONE_WITH_CONCERNS — Completed, but with issues the user should know about. List each concern.
• BLOCKED — Cannot proceed. State what is blocking and what was tried.
• NEEDS_CONTEXT — Missing information required to continue. State exactly what you need.

Escalation

It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."

Bad work is worse than no work. You will not be penalized for escalating.

• If you have attempted a task 3 times without success, STOP and escalate.
• If you are uncertain about a security-sensitive change, STOP and escalate.
• If the scope of work exceeds what you can verify, STOP and escalate.

Escalation format:

STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]

Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.

Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

Checklist

You MUST create a task for each of these items and complete them in order:

1. Explore project context — run preamble, check files, docs, recent commits
2. Offer visual companion (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
3. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
4. Propose 2-3 approaches — with trade-offs and your recommendation
5. Present design — in sections scaled to their complexity, get user approval after each section
6. Write design doc — save to docs/rkstack/specs/YYYY-MM-DD-<topic>-design.md and commit
7. Spec self-review — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
8. User reviews written spec — ask user to review the spec file before proceeding
9. Transition to implementation — invoke writing-plans skill to create implementation plan

Process Flow

digraph brainstorming {
    "Explore project context" [shape=box];
    "Visual questions ahead?" [shape=diamond];
    "Offer Visual Companion\n(own message, no other content)" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write design doc" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "Present design sections";
    "Present design sections" -> "User approves design?";
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write design doc" [label="yes"];
    "Write design doc" -> "Spec self-review\n(fix inline)";
    "Spec self-review\n(fix inline)" -> "User reviews spec?";
    "User reviews spec?" -> "Write design doc" [label="changes requested"];
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}

The terminal state is invoking writing-plans. Do NOT invoke any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.

---

Step 0: Project context

Use the preamble output to understand the tech stack. Adapt your questions to the detected languages and frameworks. If CLAUDE.md exists, read it for project conventions.

---

Step 1: Understand the idea

• Check out the current project state first (files, docs, recent commits)
• Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
• If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
• For appropriately-scoped projects, ask questions one at a time to refine the idea
• Prefer multiple choice questions when possible, but open-ended is fine too
• Only one question per message — if a topic needs more exploration, break it into multiple questions
• Focus on understanding: purpose, constraints, success criteria

---

Step 2: Explore approaches

• Propose 2-3 different approaches with trade-offs
• Present options conversationally with your recommendation and reasoning
• Lead with your recommended option and explain why
• Include Completeness: X/10 for each option (10 = all edges, 7 = happy path, 3 = shortcut)
• Show effort: (human: ~X days / CC: ~Y min). Recommend the most complete option.
• Include an Ask Codex option in every AskUserQuestion call that decides a substantive design question (architecture, tradeoff, approach). See the Ask Codex section below for the full flow. Skip it on trivial choices (naming, formatting preferences).

---

Ask Codex: second opinion on a design decision

When you call AskUserQuestion for a substantive design choice, include Ask Codex as an extra option alongside your own A/B/C. If the user picks it, Codex weighs in — endorsing some of your options, rejecting others, proposing new ones you missed, with a single top recommendation. You then re-present AskUserQuestion with the enriched set so the user decides from the merged list.

When the user picks Ask Codex:

1. Assemble the consult prompt

Build an XML-block prompt with these sections (pass verbatim as heredoc stdin, no escaping needed):

• <role> — Codex is a senior design consultant. Claude is brainstorming with the user and the user picked "Ask Codex".
• <task> — Codex reads the question, your original options with rationale, and surrounding context, then endorses/rejects each and proposes new ones if warranted. One top recommendation.
• <question> — your question verbatim.
• <claude_options> — each original option with its label and your one-line rationale.
• <context> — the spec-in-progress so far, relevant CLAUDE.md lines, referenced files, repo mode (solo/team from preamble), any constraints that matter. Terse but concrete — this is Codex's only context.
• <grounding_rules> — "Do not invent constraints. If a claim depends on an inference, say so."
• <structured_output_contract> — "Return only valid JSON matching the provided schema. Terse decision-quality rationales — this gets shown to the user inline in the follow-up AskUserQuestion."

2. Call Codex

CONSULT=$(node "${CLAUDE_PLUGIN_ROOT}/scripts/codex/consult.mjs" \
  --cwd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" \
  --effort medium \
  <<'CODEX_PROMPT'
<the assembled prompt from step 1>
CODEX_PROMPT
) ; EXIT=$?

Use timeout: 300000 (5 min). Exit codes: 0 ok, 1 Codex/parse failure, 2 usage error, 3 Codex CLI missing (tell the user to run !codex login).

3. Parse the JSON

Schema at scripts/codex/consult-schema.json. Shape:

{
  "analysis": "one-paragraph reading of the decision",
  "endorsed_existing": [{"label": "<exact label you used>", "rationale": "..."}],
  "rejected_existing": [{"label": "<exact label you used>", "reason": "..."}],
  "new_options":       [{"label": "...", "description": "...", "rationale": "..."}],
  "recommendation":     {"label": "<endorsed or new option>", "reason": "..."},
  "open_questions":    ["..."]
}

4. Re-present AskUserQuestion with Codex's input merged in

• Lead with a one-sentence summary of Codex's analysis.
• Include every original option — append Codex: <endorsement rationale> when endorsed, Codex ✗ <reason> when rejected.
• Include every new option Codex proposed — label with (Codex) and show its description.
• Mark the recommendation.label with (Recommended by Codex).
• If open_questions is non-empty, list them below the options as a brief "Codex wants to know:" footer.

Do NOT offer Ask Codex again on this same question — the user has already heard from Codex. If they still want to push further, that's a new question.

---

Step 3: Present the design

• Once you believe you understand what you're building, present the design
• Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
• Ask after each section whether it looks right so far
• Cover: architecture, components, data flow, error handling, testing
• Be ready to go back and clarify if something doesn't make sense

Design for isolation and clarity:

• Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
• For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
• Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.

Working in existing codebases:

• Explore the current structure before proposing changes. Follow existing patterns.
• Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design.
• Don't propose unrelated refactoring. Stay focused on what serves the current goal.

---

Web project design additions

If flowType is web (from detection cache):

1. Design system check. If the project has no DESIGN.md, mention it as a recommendation: "This project has no documented design system. Consider running /design-consultation to establish one before implementing UI features." Do not force this — just mention it once.

2. Visual design review. If the feature involves UI changes, invoke the /plan-design-review skill after the user approves the design but before writing the spec. This rates visual design dimensions (layout, typography, spacing, responsiveness) and suggests improvements to the design.

If flowType is not web, skip this section entirely.

---

Step 4: Write design doc

• Write the validated design (spec) to docs/rkstack/specs/YYYY-MM-DD-<topic>-design.md
  • Create the directory if needed: mkdir -p docs/rkstack/specs
  • (User preferences for spec location override this default)
• Apply humanizer constraints when writing the spec — design docs are human-facing prose
• Commit the design document to git

---

Step 5: Spec self-review

After writing the spec document, look at it with fresh eyes:

1. Placeholder scan: Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
2. Internal consistency: Do any sections contradict each other? Does the architecture match the feature descriptions?
3. Scope check: Is this focused enough for a single implementation plan, or does it need decomposition?
4. Ambiguity check: Could any requirement be interpreted two different ways? If so, pick one and make it explicit.

Fix any issues inline. No need to re-review — just fix and move on.

After self-review, invoke the dual-review skill on the spec file. This runs a Codex review loop: Codex reviews in read-only mode, you evaluate each finding against the document and source code, fix valid ones, and loop until Codex returns clean or max 3 rounds are reached. This step is automatic — do not skip it or ask the user whether to run it.

---

Step 6: User review gate

Ask the user to review the written spec before proceeding:

"Spec written and committed to <path>. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."

Wait for the user's response. If they request changes, make them and re-run the spec self-review. Only proceed once the user approves.

---

Step 7: Transition to implementation

• Invoke the writing-plans skill to create a detailed implementation plan
• Do NOT invoke any other skill. writing-plans is the next step.

---

Key Principles

• One question at a time — Don't overwhelm with multiple questions
• Multiple choice preferred — Easier to answer than open-ended when possible
• YAGNI ruthlessly — Remove unnecessary features from all designs
• Explore alternatives — Always propose 2-3 approaches before settling
• Incremental validation — Present design, get approval before moving on
• Be flexible — Go back and clarify when something doesn't make sense

Visual Companion

A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.

Offering the companion: When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:

"Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"

This offer MUST be its own message. Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.

Per-question decision: Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: would the user understand this better by seeing it than reading it?

• Use the browser for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
• Use the terminal for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions

If they agree to the companion, read the detailed guide before proceeding: skills/brainstorming/visual-companion.md