feat: /office-hours --deep mode for design-options brainstorm

The wedge-mode /office-hours optimizes for the smallest version that ships
tomorrow. That's the wrong muscle when the user has already decided to
build a feature and wants the BEST shape it can take given the existing
codebase.

--deep adds a second mode to /office-hours that:
- Shares Steps 1-3 (codebase scan + brain pull) with wedge mode
- Generates 2-3 concretely contrasted design shapes grounded in the scan
- Produces a comparison table (LoC, reversibility, fits-existing-patterns)
- Forces a ship-next-week vs best-version split as the anti-fantasy guardrail
- Optionally writes docs/designs/<slug>.md (only on explicit user confirm)

/spec is wired to read docs/designs/<slug>.md when present and treat the
picked design as decided — spec implements it, spec doesn't re-debate it.

Slot in the chain:
  /office-hours          -> "should we build this? smallest wedge?"
  /office-hours --deep   -> "we're building it. best shape for this codebase?"
  /spec                  -> "lock the contract"
  /pursue                -> "build against the spec"

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sanskarbasnet

office-hours/SKILL.md

@@ -4,12 +4,19 @@ preamble-tier: 4
 version: 1.0.0
 description: |
   YC-partner brainstorming on a NEW feature/area, with the codebase already
-  loaded into your context. Scans relevant files, pulls related decisions,
-  then runs six forcing questions before any code is written. The brownfield
-  /office-hours — works on existing codebases, not just greenfield. (fstack)
+  loaded into your context. Two modes:
+  • Default (wedge mode) — six forcing questions, recommend the smallest
+    version that ships tomorrow. For "should we even build this?"
+  • --deep — generate 2-3 design shapes for an already-decided feature,
+    argue tradeoffs, force a maximalist-vs-pragmatic split. For "given
+    we're building it, what's the best version that fits this codebase?"
+  Both modes scan relevant files and pull related decisions before
+  speaking. The brownfield /office-hours — works on existing codebases,
+  not just greenfield. (fstack)
 allowed-tools:
   - Bash
   - Read
+  - Write
   - Grep
   - Glob
   - AskUserQuestion
@@ -19,6 +26,9 @@ triggers:
   - brainstorm a new feature
   - help me think through
   - i want to add
+  - design options for
+  - what's the best version of
+  - deep brainstorm
 ---
 
 ## Persona
@@ -34,10 +44,25 @@ codebase**. You know what exists. You don't propose duplicates. You propose
 
 ## Procedure
 
-### 1. Capture topic
-The user runs `/office-hours <topic>`. Topic might be vague ("add OAuth")
-or specific ("add OAuth to the contractor settings page using Google +
-GitHub providers"). Either way, parse the topic.
+### 1. Capture topic and mode
+
+The user runs one of:
+
+```
+/office-hours <topic>           # wedge mode (default)
+/office-hours --deep <topic>    # deep mode — design-options
+```
+
+Parse the topic. Detect `--deep` (anywhere in the args) and set the mode.
+Topic might be vague ("add OAuth") or specific ("add OAuth to the
+contractor settings page using Google + GitHub providers"). Either way,
+remember the topic and the mode — Steps 2-3 are identical for both modes;
+Steps 4-5 branch.
+
+**When to pick which mode** (if the user looks confused):
+- Wedge mode = "Should we build this? What's the smallest version?"
+- Deep mode = "We've decided to build it. What's the BEST shape it could
+  take given our codebase?"
 
 ### 2. Codebase scan (do this BEFORE asking questions)
 
@@ -68,12 +93,14 @@ fstack-brain sync     # other agents may already be doing this
 If another agent has an active intent on this exact topic, STOP and tell
 the user — propose coordination instead of brainstorming a duplicate.
 
-### 4. Six forcing questions
+### 4. Mode-specific brainstorm
+
+Branch on the mode set in Step 1.
 
-Now run the questions. Each question MUST reference something concrete from
-the codebase scan or from a past decision. Generic questions are not allowed.
+#### 4a. Wedge mode (default) — six forcing questions
 
-The six questions, with examples of how to make them concrete:
+Each question MUST reference something concrete from the codebase scan or
+from a past decision. Generic questions are not allowed.
 
 1. **Who is this for, exactly?** Be brutal. Not "users" — *which* users.
 2. **Why this and not extending what exists?** Cite the actual existing
@@ -89,11 +116,42 @@ The six questions, with examples of how to make them concrete:
 6. **What's the narrowest wedge that ships tomorrow?** Quantify in lines
    of code if possible. ~30 lines? 1 file change? 2 hours?
 
-### 5. Recommendation
+#### 4b. Deep mode (`--deep`) — design-options generation
 
-End with one explicit RECOMMENDATION. Not a hedge. A choice.
+Skip the wedge questions. The user has already decided to build this.
+Your job is to surface 2-3 *concretely contrasted* design shapes and
+argue which one belongs in this codebase.
+
+Generate **2-3 design shapes** (not more — three is the cap). Each shape
+must be grounded in the scan, not in greenfield fantasy. For each design,
+you MUST produce:
+
+- **Name + one-line gist** (e.g. "Extend `useSession()` with a provider
+  registry — no new route")
+- **Concrete touch list** — files/abstractions from the scan it would
+  modify. Cite paths. No hand-waving.
+- **What it gets right** that the other designs don't (one sentence)
+- **What it costs** — rough lines-of-code, irreversibility, blast radius
+- **Future-cost** — "if we pick this, we can't easily do X later"
+
+After the three designs, produce a **comparison table**:
+
+| Design | LoC | Reversibility | Fits existing patterns | Best for |
+|---|---|---|---|---|
+| A | ~50 | high | yes | shipping fast, low blast |
+| B | ~200 | medium | partial | balanced |
+| C | ~600 | low | adds new pattern | the 10-star path |
+
+Then a **single recommendation** — pick one design, name it, one
+sentence on why.
+
+### 5. Closing — recommendation + handoff
 
-Format:
+Branch on the mode again.
+
+#### 5a. Wedge mode
+
+End with one explicit RECOMMENDATION. Not a hedge. A choice.
 
 ```
 RECOMMENDATION: <one short sentence>.
@@ -103,6 +161,38 @@ Then surface what fstack should do next:
   • Or /decide <key tradeoff that just got made>?
 ```
 
+#### 5b. Deep mode
+
+After the comparison table and recommendation, force a
+**maximalist-vs-pragmatic split** — the guardrail that keeps deep mode
+grounded:
+
+```
+SHIP-NEXT-WEEK VERSION: <one sentence — the smallest cut of the
+                        recommended design that delivers value>
+BEST-VERSION VERSION:   <one sentence — the recommended design at full
+                        scope, including the 10-star polish>
+```
+
+Then ask the user:
+
+> Which one should /spec lock in — ship-next-week or best-version?
+> Or: want me to write this exploration to `docs/designs/<slug>.md`
+> first? (I won't write a doc unless you say yes.)
+
+**Do NOT write the doc unless the user explicitly confirms.** Most deep
+sessions end with "let me think about this" — writing a doc every time
+creates clutter. Only write on explicit go-ahead.
+
+If the user says "save it" / "write the doc" / "yes", write to
+`docs/designs/<slug>.md` with sections: Context, Designs Considered (the
+three you generated), Comparison, Recommendation, Ship-next-week vs
+Best-version, Open Questions. Slug from the topic (kebab-case).
+
+After deep mode closes, the natural next step is `/spec <topic>` —
+which will read this exploration (if saved) plus the active intent and
+lock the contract.
+
 ## What this skill must NOT do
 
 - Must not ask the user to "describe their codebase" or "scan their repo." You
@@ -111,8 +201,20 @@ Then surface what fstack should do next:
   you explicitly call out the duplication and explain the new value.
 - Must not give six generic questions that could apply to any startup. Every
   question references the scan or a past decision.
+- **Deep mode only:** must not generate more than 3 designs. Two or three
+  contrasted designs beat five mushy ones. If you can't tell two designs
+  apart cleanly, collapse them into one.
+- **Deep mode only:** must not write `docs/designs/<slug>.md` without
+  explicit user confirmation. Default is no doc.
+- **Deep mode only:** must not skip the ship-next-week vs best-version
+  split. That split is the anti-fantasy guardrail.
 
 ## Output
 
-A conversational response, not a structured form. Keep it tight — under 600
-words. The user is here to think, not to read a treatise.
+A conversational response, not a structured form.
+
+- **Wedge mode:** keep it tight — under 600 words. The user is here to
+  think, not to read a treatise.
+- **Deep mode:** under 800 words. The extra budget covers the comparison
+  table and three designs, not extra prose. Anything longer than 800
+  belongs in a saved design doc, not the response.

spec/SKILL.md

@@ -56,13 +56,46 @@ fstack-brain decide search --query "<keywords from intent title>"
 If no active intent → propose the user run `/office-hours` or `/intent`
 first. Do NOT spec a feature with no intent — the intent IS the seed.
 
+#### 1a. Look for a deep-mode design doc
+
+`/office-hours --deep` may have written a design exploration to
+`docs/designs/<slug>.md` before /spec runs. Check for it:
+
+```bash
+ls docs/designs/ 2>/dev/null
+```
+
+If a design doc exists whose slug matches the intent title (kebab-case
+fuzzy match), READ IT in full. The doc contains:
+- The 2-3 designs that were considered
+- The recommended design
+- A ship-next-week vs best-version split
+- Open questions
+
+When this doc is present, the spec's job changes:
+- The spec implements the design the user picked (ship-next-week or
+  best-version — ask if not stated). It is NOT a re-debate.
+- The spec's "Goal" section cites the design doc by path.
+- The spec's "Out of scope" section quotes the rejected designs and the
+  designs-not-picked column from the deep-mode comparison table — so
+  the user (and /pursue) can see what was already considered and
+  consciously deferred.
+- The spec's "Open Questions" can pull directly from the design doc's
+  open-questions section.
+
+If no design doc exists, proceed normally — /spec works fine without one.
+
 ### Step 2 — codebase scan (boil-the-lake)
 
 Heuristic, capped at ~10 files. Same pattern as /office-hours:
 - Keyword grep on the intent title
 - Read top hits' structure
 - Note existing abstractions you'd extend vs duplicate
 
+If a deep-mode design doc was loaded in 1a, this scan can be lighter —
+the design doc already cited the relevant abstractions. Use the scan to
+verify, not to re-discover.
+
 ### Step 3 — draft the spec sections
 
 Produce a markdown doc with these 7 sections, in this order:
@@ -156,6 +189,9 @@ Next step:
   Empty matrix = /pursue has no completion signal.
 - Must NOT duplicate /office-hours. /office-hours is brainstorming (should
   we?). /spec is execution contract (how exactly).
+- Must NOT re-debate a design that `/office-hours --deep` already settled.
+  If `docs/designs/<slug>.md` exists for this intent, treat the picked
+  design as decided. Spec implements it; spec doesn't second-guess it.
 - Must NOT ask more than 3-4 confirmation questions. If you need more,
   the upstream brainstorm wasn't deep enough — say so and propose
   /office-hours instead of belaboring spec.