/wish — Plan Before You Build

Convert a validated idea into an executable wish document at .genie/wishes/<slug>/WISH.md.

When to Use

• User describes non-trivial work that needs planning before implementation.
• User wants to scope, decompose, or formalize a feature/change.
• Prior /brainstorm output exists and needs to become actionable.

Shared Worktree

This skill is collaborative and operates on the shared worktree:

• All wish artifacts live in .genie/wishes/ within the shared worktree
• State group definitions are written to the shared worktree so other agents and skills can read them
• When invoked via dispatch, acknowledges injected context (brainstorm design, file path + extracted section)

Flow

1. Gate check: if the request is fuzzy (no prior design, unclear scope, vague requirements), auto-trigger /brainstorm first. If a brainstorm/design exists, proceed. Otherwise ask: "This needs more clarity. Running /brainstorm to refine the idea first."
2. Align intent: ask one question at a time until success criteria are clear.
3. Define scope: explicit IN and OUT lists. OUT scope cannot be empty.
4. Decompose into groups: split into small, loosely coupled execution groups.
5. Write wish: create .genie/wishes/<slug>/WISH.md using the Wish Template below.
6. Add verification: every group gets acceptance criteria + a validation command.
7. Declare dependencies: declare depends-on between execution groups and cross-wish dependencies.
8. Handoff: auto-invoke /review (plan review) on the WISH.md. Do not suggest /work directly — the review gate must pass first.

Wish Document Sections

Wish Template

Use this structure when writing WISH.md:

# Wish: <Title>

| Field | Value |
|-------|-------|
| **Status** | DRAFT |
| **Slug** | `<slug>` |
| **Date** | YYYY-MM-DD |
| **Design** | [DESIGN.md](../../brainstorms/<slug>/DESIGN.md) |

## Summary
2-3 sentences: what this wish delivers and why it matters.

## Scope
### IN
- Concrete deliverable 1
- Concrete deliverable 2

### OUT
- Explicit exclusion 1 (OUT cannot be empty)

## Decisions
| Decision | Rationale |
|----------|-----------|
| Choice 1 | Why this over alternatives |

## Success Criteria
- [ ] Testable criterion 1
- [ ] Testable criterion 2

## Execution Strategy

### Wave 1 (parallel)
| Group | Agent | Description |
|-------|-------|-------------|
| 1 | engineer | <task description> |
| 2 | engineer | <task description> |

### Wave 2 (after Wave 1)
| Group | Agent | Description |
|-------|-------|-------------|
| 3 | engineer | <task description> |
| review | reviewer | Review Groups 1+2 |

## Execution Groups

### Group 1: <Name>
**Goal:** One sentence.
**Deliverables:**
1. Deliverable with acceptance criteria
2. Deliverable with acceptance criteria

**Acceptance Criteria:**
- [ ] Testable criterion

**Validation:**
```bash
# Command that exits 0 on success

depends-on: none | Group N

QA Criteria

What must be verified on dev after merge. The QA agent tests each criterion.

• <functional criterion — user-facing behavior works>
• <integration criterion — system works end-to-end>
• <regression criterion — existing behavior not broken>

Assumptions / Risks

Review Results

Populated by /review after execution completes.

Files to Create/Modify

<list of files this wish will touch>

## Task Lifecycle Integration (v4)

After writing WISH.md, create corresponding PG tasks so the wish is visible in `genie task list`:

### Step 1: Create parent task
```bash
genie task create "<wish title>" --type software

Step 2: Create child tasks per execution group

genie task create "<group title>" --parent #<parent-seq>

Step 3: Add dependencies between groups

genie task dep #<child-seq> --depends-on #<dep-seq>

Summary

Graceful degradation: If PG is unavailable or genie task commands fail, warn but do not block the wish flow. The WISH.md file is the source of truth — PG tasks are an optional tracking enhancement. The wish must still be usable by /work even if no PG tasks were created.

Rules

• No implementation during /wish — planning only.
• No vague tasks ("improve everything"). Every task must be testable.
• Keep tasks bite-sized and independently shippable.
• Declare cross-wish dependencies early with depends-on / blocks.
• OUT scope must contain at least one concrete exclusion.
• Execution Strategy is mandatory — every wish must define waves, even if sequential (single wave). This forces the planner to think about ordering, parallelism, and dependencies upfront.