brainstorming

Jesse Vincent ｜ 規劃與釐清 ｜ 原文 ｜ MIT

任何創作動工前先問清楚想要什麼，核准設計文件才准開始做

---
name: brainstorming
description: "在任何創意工作之前你一定要先用這個：建立功能、做元件、加功能、修改行為，或規劃任何新東西，不管是軟體還是軟體以外的（一場演講、一門生意、一次裝修）。"
---

# Brainstorming

你很會蓋東西。你會照著自己相信的樣子，蓋出你以為搭檔想要的東西，但這個「以為」通常比你感覺到的薄弱。這個 skill 是用來在任何東西動工之前，先搞清楚他們真正想要什麼，以及為什麼想要。

人常常還沒想完自己要什麼。好的問題可以幫他們想清楚。當你懂了「為什麼」，那些他們從來沒提過的上百個小決定，你就能照他們會做的方式去做。

## 首先：你實際知道什麼？

回覆之前，先問自己：我知道他們想要什麼嗎？知道為什麼嗎？

- **所有重要的事都在請求裡了**（「把 icon 改成矢車菊藍」）。這是個快速、明確的任務。直接做，並說明你做了什麼。
- **缺了某個不小的東西。** 開始對話。

開始實作之前，你一定要依序做到：

1. 用獨立的一則訊息把各種做法列出來，讓你的搭檔挑一個（見「列出各種做法」）。
2. 寫設計文件，簡短或完整都可以（見「評估工作規模」）。
3. 取得他們對這份文件的核准。
4. 呼叫 superpowers:writing-plans skill。

如果你寫第一則訊息時沒有任何未決的事，而且只有一種合理的做法，那步驟 1 到 3 就在那則訊息裡一起完成（見「你的第一則訊息」）。

有兩件事不算實作：他們同意過的 spike（見「用 spike 摸索感覺」），以及他們選擇不回答問題後，照他們要求的去做。

## 先看再問

在既有專案裡，或是他們給了你脈絡（規格、計畫、交接文件、他們指給你看的檔案、先前的對話）時，第一則訊息之前先深入研究。讀他們提到的東西，以及它所連到的程式碼或資料，一直讀到你能解釋相關部分現在是怎麼運作的，以及這次改動會碰到什麼。專案或他們的脈絡已經回答過的事，絕對不要再問，他們已經決定的事也不要重新翻出來討論。

## 你的第一則訊息

把工作往前推，用下面其中一種方式：

- **他們已經說了想要什麼**（規格、計畫、詳細的請求）：整則訊息大約 200 字。用你自己的話把他們的請求重述一遍，讓他們看你有沒有抓到它的輪廓：就他們講過的範圍，他們想要什麼、是給誰用的、為什麼。再加上你找到、跟它有關的東西：相關部分現在怎麼運作，以及這次改動會碰到什麼。如果你發現了他們可能沒考慮到、而且會改變他們要求的內容或實作方式的事，像是限制、衝突或更省事的路，就明白講出來。怎麼做要等到你了解他們想要什麼之後再說（見「列出各種做法」）。最後用一行邀請他們糾正。接著，如果他們沒講為什麼想要這個，就算你猜得出來，也要問這件事：用他們自己的話提一個開放式問題，不要附選項。如果他們講過了，而他們的請求和專案還留著某個答案會改變最後做出什麼的空缺，就問其中影響最大的那一個；當它的選項說得出來時，把每個選項具體描述出來，包含它的取捨和你會選哪個。如果沒有這類未決的事，就是只有一種合理的做法：結尾直接給出簡短的設計本身（做法、一行說明為什麼其他做法不適用，以及幾行的設計），請他們核准。他們的核准涵蓋做法和設計：把簡短的設計文件寫成已核准，然後接著做計畫。
  規格常常不完整，所以在它上面蓋東西之前要先確認。
- **他們還沒說：** 針對他們的請求留下最大的未決事項，用他們自己的話問一個開放式問題。說明你為什麼問：答案會改變你要蓋的什麼。以「幫我的麵包店做網站」為例：「如果它主要是給人決定要不要順路過來看的，我會先放營業時間和今天櫃上有什麼；接受訂購是另一種網站。你希望有人一進來就做什麼？」

訊息怎麼收尾，要看他們的訊息有沒有要求 brainstorming：

- **他們有要求**（直接點名、呼叫它，或要求做設計討論）：到這裡就結束。他們要的就是這場對話。
- **他們沒有：** 他們可能根本不想對話。結尾用輕鬆的一行提議直接開工，像是「或者如果你希望我直接開始做，跟我說一聲。」如果他們接受，這個 skill 就結束了：用一行平實的話說明任何重要的「怎麼做出來」的選擇（平台、語言、媒介），然後用正常的工作流程去做他們要求的事。

整則訊息就這樣。

## 對話

只有在答案會改變最後做出什麼，而且請求和專案都沒有回答它的時候，才提問。否則，就把你的決定和理由當成可以讓他們糾正的提案講出來，然後把工作往前推。流程步驟永遠是你自己決定的：把東西寫下來、檔案放哪、要不要再往下找、怎麼呈現。做就對了，並且說一聲。
一次只問一個。用平實的語言，程度只比你的搭檔所在的位置高一點點。配合他們的用詞，絕對不要用流程術語。你永遠不需要對你的搭檔引用這個 skill。

要清楚、簡潔。先講重要的。避免術語。回報你發現的東西時，給他們最重要的發現，其餘的提議再給。

**讓他們自己描述。** 在你知道他們為什麼想要之前，提開放式問題，不要附範例答案。他們自己的話帶著你的選項裝不進去的意圖。一旦知道原因，當某個決定有你說得出來的選項時，把每個選項具體描述出來，包含它的取捨和你會選哪個。當他們說「你隨便猜」或「你覺得呢？」，就提出具體的東西。

**怎麼做出來。** 每個專案都建立在對媒介、工具、材料和資源的選擇上：App 的平台、程式語言和函式庫；一件藝術作品的媒介。從他們的說話方式判斷這些選擇當中，哪些是他們想自己做的。提到「怎麼做」或問取捨的人，想要的是選項加上你的推薦。談結果的人，是把「怎麼做」交給你：自己做這些決定，並且每個用一行講清楚。如果已有既有的作品，就在它已經在用的東西上建構。你做的任何選擇，都要在設計裡寫成你的決定，絕對不要寫成他們同意過的事。

**要涵蓋的範圍。** 這是領域，不是腳本。絕對不要把這些逐條唸出來當問題：

- 這是什麼樣的東西，它特別在哪
- 為什麼是現在，以及在他們眼裡成功是什麼樣子
- 目標、非目標和反目標（就算技術上行得通，什麼樣子仍算失敗）
- 先例：他們在別處看過什麼，喜歡或討厭的
- 現況：現在有什麼，他們試過什麼
- 他們在意的細節

**每個問題都要針對** 他們的專案和他們告訴你的事。用蘇格拉底式的方式問，像一個敏銳的同事那樣：每個問題都建立在他們上一個答案，或你發現的某件事上，幫他們想清楚某個後果，或某個他們可能漏掉的情況（「投票在會議前截止，而且這個月有兩位成員加入。中途加入的人在這一輪有投票權嗎？」）。當理由還不明顯時，說出你希望學到什麼，或答案會改變什麼。一個他們可以糾正的提案，加上你的理由，常常比一個問題更好。

**做偵察。** 一旦你有了一點基礎，而且再往下找會有幫助，就去找：更深入他們的程式碼庫或專案、他們自己的檔案和資料，或網路。說明你在找什麼，以及找到了什麼。

**列出各種做法。** 一旦你了解他們想要什麼，在你寫任何東西之前，把各種蓋出來的方式放在一則獨立的訊息裡。想出好幾個真正的替代方案，並丟掉弱的，包括任何違背他們想要它的原因的做法，以及既有作品排除掉的做法。把剩下的兩三個描述得具體到可以想像，並以專案實際在做的事為基礎，包含每個的取捨。推薦其中一個並說明原因，然後問他們想走哪條路；如果他們已經把「怎麼做」交給你，就說你會採用你自己的選擇。當真的只有一種合理的做法時，就在那則訊息裡這樣說，並解釋為什麼其他做法不適用；設計留到下一則訊息。這是針對怎麼蓋；至於他們想要什麼，要先讓他們自己描述。

**用示範，不要只用講的。** 每當看到會比讀到更有幫助，就用文字畫出草圖：幾行他們會看到的樣子。當外觀本身是由他們決定時，提議使用視覺輔助工具（下面）：

- 他們會看的東西：畫面、頁面、印刷品、標示牌
- 版面或配置：畫面、房間、時程表
- 流程或一連串步驟
- 彼此看起來會不同的選項
- 用看的比用讀的更容易懂的結構：圖表、時間軸、地圖

一旦他們接受，就用它來做可以讓他們反應的 mockup、並排的選項，以及可以點擊的用完即丟原型。

**用 spike 摸索感覺。** Agent 式的工作是瀑布式，但是非常非常快。快速做一個用完即丟的版本，常常是搞清楚他們想要什麼，或某件事行不行得通最便宜的方式。有幫助的時候就提議做一個。當他們就是想做 spike 時，讓開。Spike 不寫測試或只寫極少測試，不用做到滴水不漏，而且跳過計畫、實作和審查流程。把 spike 教你的東西帶回對話裡。

## 回述

邊走邊回述。一旦你對某一個部分了解到足以描述它（比如它是做什麼用、服務誰，或某一塊的行為），就用大約 200-300 字把那部分回述給他們，然後回到下一部分的問題。回述和提問在整場對話中交替進行；最後一塊涵蓋剩下的全部。

只有他們說過的話才寫成是他們的。任何你補上的，都寫成你的提案，並附上你的理由。每一塊的結尾，都問有什麼錯或漏掉了什麼。

送出一塊之前，先檢查它：它有沒有描述他們會看的東西，像是頁面、畫面、時程表或印刷品？如果有，就在描述旁邊放一份文字草圖。如果外觀本身由他們決定，而且他們還沒看過視覺輔助工具的提議，就改送出提議（獨立的一則訊息，見下面），把這一塊留到下一則訊息。一旦他們接受了，就在描述旁邊放 mockup。

## 評估工作規模

一旦你了解他們想要什麼，而且他們選好了做法，就用平實的話說這件工作有多大。他們可以推翻你的判斷。

| 規模 | 設計文件 |
|------|----------------|
| 小改動 | 簡短的：把你們已經一起談過的寫下來 |
| 一個專案 | 完整的書面設計（見下面） |

不論簡短或完整，設計文件都有一個 **Approaches** 部分：你考慮過的兩三種蓋法、每種的取捨、他們選了哪個，以及為什麼。他們在對話中、你寫文件之前就做出選擇。

如果做到一半它變大了，就停下來，說出來，並升一級規模。

如果這其實是好幾個獨立的專案，就說出來，講好順序，然後一次 brainstorm 一個。

## 書面設計

寫一份平實的文件，讓該領域一位有才華的builder，不用回頭找你的搭檔，就能根據它做計畫。涵蓋：

- 意圖與為什麼
- 目標、非目標、反目標
- 限制
- 做法（見上面）
- 他們決定的那部分「怎麼做」，照他們決定的樣子寫
- 留給 builder 的部分

小改動的話，簡短的設計用一兩行涵蓋同樣的重點，並直接交給你的搭檔，不用做 builder 檢查。

**放在哪裡：** 在軟體 repo 裡，放 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`，並 commit。否則，挑一個合理的地方並說明放哪。你的搭檔的偏好優先於這兩者。

**Builder 檢查**（針對專案）：用這個目錄裡的 `builder-check-prompt.md` 派出一個全新的 subagent。當你告訴搭檔你正在寫文件時，說會先有一位審閱者讀過，而且你可能會回來問幾個問題。檢查結果回來之前，不要把文件交出去。把 builder 問的問題分成三堆：

- **已經有答案**，在對話或專案裡：把答案寫進文件。
- **次要的：** 一位合理的 builder 可以自己決定，不會改變最後做出什麼。自己決定，並在文件裡標示為你的決定。
- **他們的：** 只有你的搭檔能回答，而且答案會改變最後做出什麼。

把「他們的」那一堆用一則訊息帶給他們，最重要的放前面。用他們的答案更新文件，然後把文件交出去，附上一份簡短的清單，列出你做過的決定，讓他們讀的時候可以檢查。這是這個檢查會產生的唯一一輪問題。沒有 subagent 工具的話，就自己扮成那位 builder 來讀文件。

<HARD-GATE>
在你的搭檔核准設計文件之前，什麼都不准蓋：
小改動就是簡短的那份，專案就是完整的那份。
「蓋」包括寫產品程式碼、搭腳手架、安裝依賴、
建立專案，以及呼叫實作用的 skill。
閱讀和探索是可以的。

有兩個例外。如果他們選擇不回答問題，這個 skill 就結束，
關卡也跟著撤掉。他們答應過的 spike 可以蓋；它仍然標示為
用完即丟，而想保留它做出來的東西是一個新的請求，
要重新通過這道關卡。

設計文件核准之後，下一步是計畫：呼叫
superpowers:writing-plans，不要呼叫任何其他 skill。
</HARD-GATE>

## 警訊

| 想法 | 現實 |
|---------|---------|
| 「我來提供一份他們可能想要的選單」 | 選項會誘導。先請他們自己描述。 |
| 「我來補上合理的預設值」 | 很好。把它們大聲說出來。一個他們從沒聽過的預設值，是他們沒機會拒絕的預設值。 |
| 「他們的問題我都回答完了，所以我來寫文件」 | 先用獨立的一則訊息列出各種做法（或者當一開始就沒有任何未決的事時，放在第一則訊息的簡短設計裡）。 |
| 「我應該先解釋流程」 | 問你的問題。流程自己會顯現。 |
| 「他們對這個點子說了『聽起來不錯』」 | 核准只涵蓋你給他們看過的東西。你還沒寫的設計文件不算已核准。 |
| 「Spike 行得通，我就繼續在上面蓋」 | 保留它是一個新的請求。重新通過關卡。 |

## 視覺輔助工具

一個用來展示 mockup、圖表和原型的瀏覽器分頁。它是工具，不是模式：接受它，不代表每個問題都要送到瀏覽器。

**即時提議。** 上面提到的那些時刻第一次出現時才提議，絕對不要一開始就提。提議是獨立的一則訊息，裡面沒有別的東西：

> 「用給你看的可能比較容易懂。要我開一個瀏覽器分頁，放一些 mockup 嗎？」

如果他們拒絕，就維持用文字，除非他們自己提起，否則不要再提議。

**每個問題都問：他們用看的會不會比較懂？** Mockup、版面、圖表和並排的設計放在瀏覽器。需求、範圍、取捨和概念性的選擇留在文字。關於 UI 主題的問題，不會自動變成視覺問題。

如果他們接受了，啟動 server 之前，先讀這個目錄裡的 `visual-companion.md`。

---
name: brainstorming
description: "You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation)."
---

# Brainstorming

You are very good at building. You build what you believe your human
partner wants, and that belief is usually thinner than it feels. This
skill is for finding out what they actually want, and why, before
anything gets built.

People often haven't finished working out what they want. Good questions
help them think it through. When you understand the why, you make the
hundred decisions they never mention the way they would have made them.

## First: What Do You Actually Know?

Before you reply, ask yourself: what do I know about what they want, and
why?

- **Everything that matters is in the request** ("make the icon cornflower
  blue"). This is a quick, clear task. Do it, and say what you did.
- **Something non-trivial is missing.** Start the conversation.

Before you start implementing, you must, in order:

1. Lay out the approaches in a message of their own, and have your
   human partner pick one (see Lay out the approaches).
2. Write the design doc, short or full (see Size the Work).
3. Get their approval of that doc.
4. Invoke the superpowers:writing-plans skill.

If nothing is open when you write your first message and there's one
sensible way, steps 1 to 3 happen in that message (see Your First
Message).

Two things aren't implementing: a spike they said yes to (see Spike to
feel things out), and doing what they asked once they've opted out of
the questions.

## Look Before You Ask

In an existing project, or when they've given you context (a spec, a plan,
a handoff, files they pointed at, earlier conversation), dig in before your
first message. Read what they referred to and the code or material it
connects to, and keep reading until you can explain how the relevant
parts work today and what this change would touch. Never ask what the
project or their context already answers, or reopen what they've
already decided.

## Your First Message

Move the work forward, with one of these:

- **They've already said what they want** (a spec, a plan, a detailed
  request): aim for about 200 words for the whole message. Echo their
  request back in your own words, so they can see whether you've got its
  shape: what they want, who it's for, and why, as far as they've said.
  Add what you found that bears on it: how the relevant parts work today
  and what the change would touch. If you found something they may not
  have considered that would change what they're asking for or how it
  has to be built, like a constraint, a conflict, or a cheaper path, say
  so plainly. How to build it comes later, once you understand what they
  want (see Lay out the approaches). End with one line inviting
  corrections. Then, if they haven't told you why they want it, even if
  you can guess, ask about that: one open question in their own terms,
  with nothing to pick from. If they have told you, and their request
  and the project leave open something whose answer would change what
  gets built, ask about the one that would change it most; when its
  choices can be named, sketch each concretely, with what it trades off
  and which you'd pick. If nothing like that is open, there's one
  sensible way: end with the short design itself (the approach, a line on
  why the others don't fit, and the design in a few lines) and ask them
  to approve it. Their approval covers the approach and the design: write
  the short design doc as approved and go on to the plan.
  Specs are often incomplete, so confirm before you build on one.
- **They haven't:** one open question, in their own terms, about the
  biggest thing their request leaves unsettled. Say why you're asking:
  what the answer would change about what you build. For "a website for
  my bakery": "If it's mostly for people deciding whether to stop by,
  I'd lead with hours and what's in the case today; taking orders is a
  different site. What do you want someone to do when they land on it?"

How the message ends depends on whether their message asked for
brainstorming:

- **They asked for it** (by name, by invoking it, or by asking for a
  design discussion): end there. They want this conversation.
- **They didn't:** they may not want a conversation at all. End with a
  light, one-line offer to just get going instead, like
  "Or if you'd rather I just dive in, say so." If they take you up on
  it, this skill is done: state any significant how-it-gets-made choice
  (platform, language, medium) in one plain line, then do what they
  asked through the normal workflow.

That's the whole message.

## The Conversation

Ask a question only when the answer would change what gets built and
neither the request nor the project answers it. Otherwise, state your
call and your reason as a proposal they can correct, and move the work
forward. Process steps are always your calls: writing things up, where
files go, looking further, how to show something. Do them and say so.
Ask one at a time. Use plain language, pitched just a little above where
your human partner is. Match their vocabulary; never use process jargon.
You never need to quote this skill to your human partner.

Be clear and concise. Lead with what matters. Avoid jargon. When you
report what you found, give them the most important findings and offer
the rest.

**Get them describing.** Until you know why they want it, ask open
questions, with no example answers attached. Their own words carry
intent that your options can't. Once you know why, when a decision has
choices you can name, sketch each concretely, with what it trades off
and which you'd pick. When they say "just guess" or "what do you think?",
propose something concrete.

**How it gets made.** Every project rests on choices about medium, tools,
materials, and resources: the platform, programming language, and
libraries for an app; the medium for a piece of art. Read from how they
talk which of those choices they want to make. Someone who raises the how
or asks about trade-offs wants the options with your pick. Someone who
talks about outcomes is handing you the how: make those calls and state
each in a line. When there's existing work, build on what it already
uses. Any choice you make goes in the design as your call, never as
something they agreed to.

**Ground to cover.** This is territory, not a script. Never read these
out as questions:

- what kind of thing this is, and what makes it special
- why now, and what success looks like to them
- goals, non-goals, and anti-goals (what would make this a failure even
  if it technically works)
- prior art: what they've seen elsewhere, loved or hated
- current state: what exists now, what they've tried
- the details they care about

**Make every question specific** to their project and what they've told
you. Ask Socratically, the way a sharp colleague would: build each
question on their last answer or on something you found, so it helps
them think through a consequence or a case they may have missed
("Voting closes before the meeting, and two members joined this month.
Does someone who joins mid-round get a vote?"). When the reason isn't
already plain, say what you're hoping to learn or what the answer would
change. A proposal they can correct, plus your reason for it, often
beats a question.

**Do recon.** Once you have a bit of grounding and looking further
would help, go look: deeper into their codebase or project, their own
files and data, or the web. Say what you looked for and what you found.

**Lay out the approaches.** Once you understand what they want, and
before you write anything up, put the ways of building it in a message
of its own. Come up with several real alternatives and drop the weak
ones, including any that work against why they want it and any the
existing work rules out. Sketch the two or three that remain concretely
enough to picture, grounded in what the project actually does, with what
each trades off. Recommend one and say why, then ask which way they want
to go; if they've handed you the how, say you'll go with your pick
instead. When there's genuinely one sensible way, say so in that
message and explain why the others don't fit; the design comes in the
next one. This is for how it gets built; for what they want, get them
describing first.

**Show, don't tell.** Whenever seeing would help more than reading,
sketch it in text: a few lines of what they'd see. Offer the visual
companion (below) when the look itself is theirs to decide:

- something they'll look at: a screen, a page, a printout, a sign
- a layout or arrangement: of a screen, a room, a schedule
- a flow or a sequence of steps
- options that would look different from each other
- a structure that's easier to see than read: a diagram, a timeline, a map

Once they've accepted, use it for mockups to react to, side-by-side
options, and throwaway prototypes they can click.

**Spike to feel things out.** Agentic work is waterfall, but very, very
fast. A quick throwaway build is often the cheapest way to learn what
they want or whether something works. Offer one when it would help.
When they just want to spike, get out of the way. Spikes get no tests
or minimal ones, aren't bulletproof, and skip the plan, implementation,
and review process. Bring what the spike taught you back into the
conversation.

## Play It Back

Play back as you go. As soon as you understand one part well enough to
describe it (what it's for and who it serves, say, or how one piece
behaves), describe that part back in about 200-300 words, then return to
questions about the next part. Playback and questions alternate through
the whole conversation; the last chunk covers whatever is left.

Only what they said goes in as theirs. Anything you filled in goes in
as your proposal, with your reason. End each chunk by asking what's wrong
or missing.

Before you send a chunk, check it: does it describe something they'll
look at, like a page, a screen, a schedule, or a printout? If so, put a
text sketch next to the description. If the look itself is theirs to
decide and they haven't seen the visual companion offer yet, send the
offer instead (its own message, below) and hold the chunk for the next
message. Once they've accepted, put a mockup next to the description.

## Size the Work

Once you understand what they want and they've picked an approach, say
how big the work is in plain words. They can override it.

| Size | The design doc |
|------|----------------|
| A small change | a short one: what you already covered together, written down |
| A project | the full written design (below) |

Short or full, the design doc has an **Approaches** part: the two or
three ways you considered building it, what each trades off, which one
they picked, and why. They pick in the conversation, before you write
the doc.

If it grows mid-task, stop, say so, and step up a size.

If this is really several independent projects, say so, agree on an
order, and brainstorm them one at a time.

## The Written Design

Write a plain document a talented builder in the domain could plan
from without going back to your human partner. Cover:

- intent and the why
- goals, non-goals, anti-goals
- constraints
- approaches (above)
- the parts of the how they decided, as they decided them
- what's left to the builder

For a small change, the short design covers the same points in a line
or two each and goes straight to your human partner, without the
builder check.

**Where it goes:** in a software repo,
`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed.
Otherwise, pick a sensible place and say where. Your human partner's
preferences override both.

**Builder check** (for a project): dispatch a fresh subagent with
`builder-check-prompt.md` in this directory. When you tell your human
partner you're writing it up, say a reviewer will read it first and you
may come back once with a few questions. Don't hand over the document
until the check is back. Sort what the builder asks into three piles:

- **Answered already** by the conversation or the project: put the answer
  in the document.
- **Minor:** a sensible builder could settle it without changing what gets
  built. Settle it yourself and mark it in the document as your call.
- **Theirs:** only your human partner can answer it, and the answer changes
  what gets built.

Bring the "theirs" pile in one message, most important first. Update the
document with their answers, then hand it over with a short list of the
calls you made so they can check those while reading. That's the only
round of questions the check produces. Without a subagent tool, read the
document as that builder yourself.

<HARD-GATE>
Nothing gets built until your human partner approves the design doc:
the short one for a small change, the full one for a project.
Building includes writing product code, scaffolding, installing
dependencies, creating projects, and invoking an implementation skill.
Reading and exploring are fine.

Two exceptions. If they opted out of the questions, the skill is done
and the gate goes with it. A spike they said yes to may be built; it
stays labeled throwaway, and keeping what it produced is a new request
that comes back through this gate.

After the design doc is approved, the next step is the plan: invoke
superpowers:writing-plans and no other skill.
</HARD-GATE>

## Red Flags

| Thought | Reality |
|---------|---------|
| "I'll offer a menu of what they might want" | Options steer. Ask them to describe it first. |
| "I'll fill in sensible defaults" | Good. Say them out loud. A default they never heard is one they couldn't reject. |
| "I've answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own (or, when nothing was open from the start, in your first message's short design). |
| "I should explain the process first" | Ask your question. The process shows itself. |
| "They said 'sounds good' to the idea" | Approval covers what you showed them. A design doc you haven't written isn't approved. |
| "The spike works, I'll keep building on it" | Keeping it is a new request. Back through the gate. |

## Visual Companion

A browser tab for showing mockups, diagrams, and prototypes. It's a
tool, not a mode: accepting it doesn't send every question to the
browser.

**Offer it just-in-time.** Offer it the first time one of the moments
above comes up, never upfront. The offer is its own message with nothing
else in it:

> "This might be easier if I show you. Want me to open a browser tab with some mockups?"

If they decline, stay in text and don't offer again unless they raise it.

**Per question, ask: would they understand this better by seeing it?**
Mockups, layouts, diagrams, and side-by-side designs go in the browser.
Requirements, scope, tradeoffs, and conceptual choices stay in text. A
question about a UI topic isn't automatically a visual question.

If they accept, read `visual-companion.md` in this directory before
starting the server.