# Phase 4: Alternatives Generation (MANDATORY)

Produce 2-3 distinct implementation approaches. This is NOT optional.

## Contents

- [Visual Sketch (UI ideas only)](#visual-sketch-ui-ideas-only)


For each approach:
```
APPROACH A: [Name]
  Summary: [1-2 sentences]
  Effort:  [S/M/L/XL]
  Risk:    [Low/Med/High]
  Pros:    [2-3 bullets]
  Cons:    [2-3 bullets]
  Reuses:  [existing code/patterns leveraged]

APPROACH B: [Name]
  ...

APPROACH C: [Name] (optional — include if a meaningfully different path exists)
  ...
```

Rules:
- At least 2 approaches required. 3 preferred for non-trivial designs.
- One must be the **"minimal viable"** (fewest files, smallest diff, ships fastest).
- One must be the **"ideal architecture"** (best long-term trajectory, most elegant).
- One can be **creative/lateral** (unexpected approach, different framing of the problem).
- If the second-opinion subagent proposed a prototype in Phase 3.5, consider using it as a starting point for the creative/lateral approach.

**RECOMMENDATION:** Choose [X] because [one-line reason].

Present via AskUserQuestion. Do NOT proceed without user approval of the approach.

---

## Visual Sketch (UI ideas only)

If the chosen approach involves user-facing UI (screens, pages, forms, dashboards,
or interactive elements), generate a rough wireframe to help the user visualize it.
If the idea is backend-only, infrastructure, or has no UI component — skip this
section silently.

**Step 1: Gather design context**

1. Check if `DESIGN.md` exists in the repo root. If it does, read it for design
   system constraints (colors, typography, spacing, component patterns). Use these
   constraints in the wireframe.
2. Apply core design principles:
   - **Information hierarchy** — what does the user see first, second, third?
   - **Interaction states** — loading, empty, error, success, partial
   - **Edge case paranoia** — what if the name is 47 chars? Zero results? Network fails?
   - **Subtraction default** — "as little design as possible" (Rams). Every element earns its pixels.
   - **Design for trust** — every interface element builds or erodes user trust.

**Step 2: Generate wireframe HTML**

Generate a single-page HTML file with these constraints:
- **Intentionally rough aesthetic** — use system fonts, thin gray borders, no color,
  hand-drawn-style elements. This is a sketch, not a polished mockup.
- Self-contained — no external dependencies, no CDN links, inline CSS only
- Show the core interaction flow (1-3 screens/states max)
- Include realistic placeholder content (not "Lorem ipsum" — use content that
  matches the actual use case)
- Add HTML comments explaining design decisions

Write to a temp file:
```bash
SKETCH_FILE="/tmp/workflow-sketch-$(date +%s).html"
```

**Step 3: Render and capture**

```bash
agent-browser open "file://$SKETCH_FILE"
agent-browser screenshot /tmp/workflow-sketch.png
```

If `agent-browser` is not available, skip the render step. Tell the
user: "Visual sketch requires the agent-browser CLI. Install with `npm i -g agent-browser` to enable it."

**Step 4: Present and iterate**

Show the screenshot to the user. Ask: "Does this feel right? Want to iterate on the layout?"

If they want changes, regenerate the HTML with their feedback and re-render.
If they approve or say "good enough," proceed.

**Step 5: Include in design doc**

Reference the wireframe screenshot in the design doc's "Recommended Approach" section.
The screenshot file at `/tmp/workflow-sketch.png` can be referenced by downstream skills
(`/plan-design-review`, `/design-review`) to see what was originally envisioned.

**Step 6: Outside design voices** (optional)

After the wireframe is approved, offer outside design perspectives via AskUserQuestion:

> "Want outside design perspectives on the chosen approach? Two Claude subagents with fresh context can propose alternative visual theses and design directions."
>
> A) Yes — get outside design voices
> B) No — proceed without

If user chooses A, dispatch two parallel subagents via the Agent tool:

1. **Visual thesis subagent:**
"For this product approach, provide: a visual thesis (one sentence — mood, material, energy), a content plan (hero → support → detail → CTA), and 2 interaction ideas that change page feel. Apply beautiful defaults: composition-first, brand-first, cardless, poster not document. Be opinionated."

2. **Design direction subagent:**
"For this product approach, what design direction would you recommend? What aesthetic, typography, and interaction patterns fit? What would make this approach feel inevitable to the user? Be specific — font names, hex colors, spacing values."

Present outputs under `VISUAL THESIS (subagent):` and `DESIGN DIRECTION (subagent):` headers.

**Error handling:** All non-blocking. On subagent failure, skip that voice and continue with whatever succeeded.