Zed

---
description: Experimental skill for semantic question syntax. Tests $token expansions for AskUserQuestion.
argument-hint: [slug] [prompt]
allowed-tools:
  - Read
  - Write
  - AskUserQuestion
  - Skill
  - Bash(mkdir:*)
model: inherit
context: inherit
hooks: {}
user-invocable: false
---

# Zed

<purpose>
Dream extraction, not requirements gathering. Transforms user's interview answers (or interactive dialogue) into a structured PROJECT.md.

You are a **thinking partner**, not an interviewer. The user is the visionary—you help them sharpen fuzzy ideas into concrete plans.
</purpose>

<constraints>
**Your role:**
- Follow their energy and emphasized points
- Challenge vagueness persistently
- Make abstract concepts concrete through examples
- Stop when you understand the what, why, who, and definition of done
</constraints>

<antipatterns>
**Not your role:**
- Checklist walking through questions
- Accepting vague answers to move faster
- Imposing technical constraints before understanding the vision
- Rushing to generate the PROJECT.md

**Anti-patterns to avoid:**
- Walking through questions like a checklist
- Accepting vague answers to move faster
- Corporate jargon
- Rushing to the next topic
- Premature technical constraints
</antipatterns>

<invariants>
- User's exact words quoted in Vision section
- Success criteria are testable (not vague)
- Priority stack enables informed scope cuts
- Out of scope is explicit with reasoning
- Core essence captures the ONE non-negotiable
- No assumptions left unverified
</invariants>

<progress>
- [ ] Step 1: Conversational dialogue (no tools)
- [ ] Step 2: Visual review (semantic tokens + tree/box/table previews)
- [ ] Step 3: Clarification dialogue
- [ ] Step 4: Architecture confirmation (full preview with diagrams + tables)
- [ ] Step 5: Write PROJECT.md
- [ ] Step 6: Continue to next phase
</progress>

## Input

- **$1** — Plan slug (directory name, single word)
- **$2+** — Feature prompt (what to build, can be multi-word)

Plan directory: `.claude/plans/$1/`

---

## Step 1: Conversational Dialogue

<skill name="orc:zed-conversation" args="$2" />

Returns:
- **In your words** — quoted user description
- **Building** — what we're making
- **Why** — motivation
- **For** — who it's for
- **Done means** — testable criteria
- **Core essence** — the ONE non-negotiable
- **Out of scope** — what we won't build
- **Survives 50% cut** — priority stack

---

## Step 2: Review Understanding

Validate what emerged from the conversation using semantic tokens. **All 4 questions in ONE batched call.** Each option MUST include a `preview` field with visual confirmation artifacts.

```xml
<AskUserQuestion>
  <Question
    question="$review-flow-question-from-context"
    header="Flow"
    multiSelect="false"
    options="$user-story-arrows:4"
  />
  <Question
    question="$review-actors-question-from-context"
    header="Actors"
    multiSelect="true"
    options="$actors-from-context"
  />
  <Question
    question="$review-core-question-from-context"
    header="Core"
    multiSelect="false"
    options="$core-essence-from-context:3"
  />
  <Question
    question="$review-boundaries-question-from-context"
    header="Boundaries"
    multiSelect="true"
    options="$anti-scope-from-context:4"
  />
</AskUserQuestion>
```

### Preview Requirements for Step 2

**Flow options** — each preview shows a tree execution diagram:

```
preview: |
  User Flow: [option label]

  [Actor]
  └─ [Action 1]
     └─ [System Response]
        └─ [Action 2]
           └─ [Outcome]

  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
  │  [Start]     │───▶│  [Process]   │───▶│  [End]       │
  │  trigger     │    │  transform   │    │  result      │
  └──────────────┘    └──────────────┘    └──────────────┘
```

**Actor options** — each preview shows a responsibility table:

```
preview: |
  Actor: [name]

  | Responsibility     | Interaction          |
  |--------------------|----------------------|
  | [what they do]     | [what they touch]    |
  | [what they own]    | [what they see]      |

  Boundaries:
  ├─ Can: [actions]
  └─ Cannot: [restrictions]
```

**Core essence options** — each preview shows what it protects:

```
preview: |
  Core: [candidate]

  ┌─────────────────────────────────┐
  │  NON-NEGOTIABLE                 │
  │  [the one thing]                │
  │                                 │
  │  If this breaks, nothing works: │
  │  • [consequence 1]              │
  │  • [consequence 2]              │
  └─────────────────────────────────┘

  Survives:
  ├─ 50% scope cut? ✓
  ├─ Timeline halved? ✓
  └─ Team reduced?   ✓
```

**Boundary options** — each preview shows in/out scope:

```
preview: |
  Boundary: [item]

  ┌─ IN SCOPE ─────────────────────┐
  │ • [what we build]              │
  │ • [what we handle]             │
  └────────────────────────────────┘
  ┌─ OUT OF SCOPE ─────────────────┐
  │ • [what we skip]               │
  │ • [why: reason]                │
  └────────────────────────────────┘
```

---

## Step 3: Clarify Gaps

Scan for gaps and vagueness from the conversation. **Generate questions targeting what was vague in THIS conversation.** Skip individual questions (not whole calls) if that topic was already clear.

### Vagueness Detection

Look for BOTH:
1. **Predefined patterns**: "clean UX", "fast", "simple", "intuitive", "users", "should work", "easy to use", "seamless"
2. **AI inference**: Novel vague terms specific to THIS conversation (e.g., "visual simplicity", "natural flow", "feels right")

### Call 1: Priority, Success, Expand

```xml
<AskUserQuestion>
  <Question
    question="$clarify-priority-question-from-context"
    header="Priority"
    multiSelect="false"
    options="$priority-stack-from-context"
  />
  <Question
    question="$clarify-success-question-from-context"
    header="Success"
    multiSelect="true"
    options="$acceptance-criteria:4"
  />
  <Question
    question="$expand-terse-answer-from-context"
    header="Expand"
    multiSelect="false"
    options="$elaborations-from-context:3"
  />
</AskUserQuestion>
```

### Call 2: Testability, Disambiguate, Concretize

```xml
<AskUserQuestion>
  <Question
    question="$verify-testability-from-context"
    header="Test"
    multiSelect="false"
    options="$testable-assertions-from-context:3"
  />
  <Question
    question="$disambiguate-term-from-context"
    header="Clarify"
    multiSelect="false"
    options="$term-interpretations-from-context:3"
  />
  <Question
    question="$concretize-vague-from-context"
    header="Concrete"
    multiSelect="false"
    options="$concrete-examples-from-context:3"
  />
</AskUserQuestion>
```

### Required Clarifications

- If Core Essence is vague → ask for specific observable behavior
- If Success Criteria aren't testable → ask for specific assertions
- If Priorities don't enable scope cuts → ask what survives if we cut 50%
- If Boundaries are implied → ask what's explicitly NOT being built

Stop when you can answer:
- What are we building?
- Why does it exist?
- Who is it for?
- What does "done" look like?

---

## Step 4: Verify Understanding

Present the full architecture summary as a preview on the Confirm option. The user sees the complete plan visualization before approving.

```xml
<AskUserQuestion>
  <Question
    question="Does this capture your vision accurately?"
    header="Verify"
    multiSelect="false"
    options="$confirm-with-architecture-preview"
  />
</AskUserQuestion>
```

### Preview for $confirm-with-architecture-preview

The **Confirm** option MUST have a preview that combines all artifacts into one view. Generate this from context:

```
preview: |
  ┌─ VISION ───────────────────────────────┐
  │ "[user's exact words quoted]"           │
  └─────────────────────────────────────────┘

  What: [concrete description]
  Why:  [motivation]
  Who:  [target users]

  ┌─ CORE ESSENCE ─────────────────────────┐
  │ [the ONE non-negotiable]               │
  └─────────────────────────────────────────┘

  Architecture:
  [Actor 1]
  └─ [action] ──▶ [System]
     └─ [process] ──▶ [outcome]
  [Actor 2]
  └─ [action] ──▶ [System]
     └─ [process] ──▶ [outcome]

  | Priority | Feature              | Survives 50% cut? |
  |----------|----------------------|--------------------|
  | P0       | [core feature]       | Yes                |
  | P1       | [important feature]  | Yes                |
  | P2       | [nice to have]       | No                 |

  ┌─ SUCCESS CRITERIA ─────────────────────┐
  │ ☐ [testable criterion 1]              │
  │ ☐ [testable criterion 2]              │
  │ ☐ [testable criterion 3]              │
  └─────────────────────────────────────────┘

  ┌─ OUT OF SCOPE ─────────────────────────┐
  │ ✗ [excluded 1] — [reason]             │
  │ ✗ [excluded 2] — [reason]             │
  └─────────────────────────────────────────┘
```

The **Cancel** option preview shows what happens next:

```
preview: |
  What happens if you cancel:

  • Return to Step 3 (Clarify Gaps)
  • You can correct any misunderstanding
  • Nothing is written yet — PROJECT.md
    is only created in Step 5

  Tell me what I got wrong and I'll fix it.
```

Wait for user confirmation or corrections.

---

## Step 5: Write PROJECT.md

Write `.claude/plans/$1/PROJECT.md`. Include sections **only if they add value** for this specific project:

### Required Sections

| Section | Contents |
|---------|----------|
| **Vision** | User's exact words quoted |
| **What We're Building** | Concrete description |
| **Why It Exists** | Motivation/problem solved |
| **Who It's For** | Target users |
| **Core Essence** | The ONE non-negotiable |
| **Success Criteria** | Testable checkboxes |
| **Out of Scope** | What we won't build + reasoning |

### Optional Sections (include when useful)

| Section | When to Include |
|---------|-----------------|
| **User Flow** | When there's a clear `Actor → Action → Outcome` sequence |
| **Actors** | When multiple actors interact with the system |
| **UI Layout** | When visual structure is part of the core essence |
| **Priority Stack** | When scope cuts are likely needed |
| **Technical Notes** | When implementation constraints were discussed |
| **Definition of Done** | When success criteria need a summary statement |

### User Flow Format

When the project has clear flows, use arrow notation:

```
User → runs command → sees TUI → converses → gets artifact
Admin → approves request → triggers notification → updates state
```

### Principles

- Quote user's exact words in Vision
- Success criteria must be testable (checkboxes)
- Out of scope needs reasoning, not just a list
- Priority stack enables informed scope cuts
- Skip sections that would just be filler

---

## Step 6: Continue to Next Phase

```xml
<AskUserQuestion>
  <Question
    question="Ready to continue to the next phase?"
    header="Continue"
    multiSelect="false"
    options="$continue"
  />
</AskUserQuestion>
```

---

## Semantic Tokens Reference

### Static Tokens

| Token | Expands to |
|-------|------------|
| `$yesno` | Yes / No |
| `$confirm` | Confirm / Cancel |
| `$confirm-with-architecture-preview` | Confirm (with full architecture preview) / Cancel (with next-steps preview) |
| `$continue` | Continue / Pause / Stop |

### Generative Tokens

| Token | Generates |
|-------|-----------|
| `$user-story-arrows:n` | n user flows as `Actor → Action → Outcome` |
| `$actors-from-context` | Inferred actors from conversation |
| `$core-essence-from-context:n` | n candidates for the non-negotiable core |
| `$anti-scope-from-context:n` | n things explicitly out of scope |
| `$priority-stack-from-context` | Features ranked by survival priority |
| `$acceptance-criteria:n` | n testable success criteria |
| `$quality-attributes-from-context` | Inferred quality attributes (fast, simple, etc.) |

### Review Tokens (Step 2)

| Token | Generates |
|-------|-----------|
| `$review-flow-question-from-context` | Question validating the user flow from conversation |
| `$review-actors-question-from-context` | Question confirming actors discussed |
| `$review-core-question-from-context` | Question validating the core essence |
| `$review-boundaries-question-from-context` | Question confirming out-of-scope items |

### Clarification Tokens (Step 3)

| Token | Generates |
|-------|-----------|
| `$clarify-priority-question-from-context` | Question about priority/tradeoffs |
| `$clarify-success-question-from-context` | Question about success criteria |
| `$expand-terse-answer-from-context` | Question expanding single-word answers |
| `$elaborations-from-context:n` | n elaborations of terse responses |
| `$verify-testability-from-context` | Question making vague criteria testable |
| `$testable-assertions-from-context:n` | n testable assertions from vague statements |
| `$disambiguate-term-from-context` | Question clarifying undefined terms |
| `$term-interpretations-from-context:n` | n possible meanings of ambiguous terms |
| `$concretize-vague-from-context` | Question requesting concrete specifics |
| `$concrete-examples-from-context:n` | n concrete examples from abstract statements |

### Expansion Rules

When expanding a `$token`, generate options where:
- **label**: Concise display text (arrow diagrams for flow tokens)
- **description**: One sentence explaining the option
- **preview**: Visual confirmation artifact (REQUIRED for Steps 2 and 4)

### Preview Generation Rules

Every option in Steps 2 and 4 MUST include a `preview` field. Use these visual formats:

**Tree execution diagrams** — for flows, processes, sequences:
```
[Trigger]
├─ [Step 1]
│  └─ [Sub-step]
├─ [Step 2]
│  ├─ [Branch A] ──▶ [Outcome A]
│  └─ [Branch B] ──▶ [Outcome B]
└─ [Step 3]
   └─ [Result]
```

**ASCII box diagrams** — for architecture, components, boundaries:
```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  [Component] │───▶│  [Process]   │───▶│  [Output]    │
│  details     │    │  details     │    │  details     │
└──────────────┘    └──────────────┘    └──────────────┘
```

**Tables** — for comparisons, priorities, feature matrices:
```
| Column 1   | Column 2       | Column 3 |
|------------|----------------|----------|
| [data]     | [data]         | [data]   |
```

**Scope boxes** — for in/out boundaries:
```
┌─ IN SCOPE ────────────────┐
│ • [included item]         │
└───────────────────────────┘
┌─ OUT OF SCOPE ────────────┐
│ ✗ [excluded] — [reason]  │
└───────────────────────────┘
```

### Combining Formats

Previews should combine multiple formats when appropriate. For example, the Step 4 verification preview combines boxes (vision, core), trees (architecture), tables (priorities), and checklists (success criteria) into a single comprehensive view.

Keep previews scannable — use whitespace between sections. Max ~40 lines per preview.