Menu Command

Create a lightweight epic-level spec for the initiative described in $ARGUMENTS.

This is the PM's first step: define WHAT to build and WHY.

Workflow

Step 1: Investigate Codebase

Use Grep, Glob, Read to understand:

• Existing features related to this initiative
• Current architecture and patterns
• Potential impact areas

Step 2: Clarify Requirements

Use AskUserQuestion iteratively:

• 2-4 questions per round
• 2-4 concrete options per question
• Focus categories:
  • Why: Business reason for this initiative
  • Hypothesis: What we expect to validate
  • Scope: What to include / exclude
  • Users: Target users, personas
  • Success criteria: How we measure success
  • Risks: What could go wrong

Keep iterating until Why, hypothesis, and scope are clear.

Step 3: Create Worktree & Spec Directory

Create a docs-only worktree for this epic:

EnterWorktree({ name: "docs/<epic>" })

Then inside the worktree, create docs/specs/<epic>/ with 2 files:

docs/specs/<epic>/
├── overview.md
└── scope.md

<epic> is a slug derived from user input (e.g., "PDF export feature" -> pdf-export).

overview.md

# <Epic Name>

## Summary

<!-- 1-2 sentence project overview -->

## Background & Purpose

<!-- Why is this project needed? User pain points, business rationale -->

## Why Now

<!-- Urgency, timing rationale -->

## Hypothesis

<!-- What we want to validate. Use "If we <action>, then <outcome>" format -->

- Hypothesis 1:
- Hypothesis 2:

## Expected Outcome

<!-- What we gain if hypotheses are correct -->

scope.md

# Scope: <Epic Name>

## In Scope

-

## Out of Scope

-

## Success Criteria (KPI)

### Expected to Improve

-

### At Risk (may decrease)

-

## Acceptance Gates

<!-- Conditions for PM to approve release -->

- [ ]

## Experiment Info (if applicable)

- Flag name:
- Variants:
- Traffic split %:

Step 4: User Confirmation

Present generated files for review. Handle modifications if requested.

Step 5: Create Docs-Only PR

Commit and push the spec documents:

git add docs/specs/<epic>/overview.md docs/specs/<epic>/scope.md
git commit -m "docs: <epic> スペック追加"
git push -u origin HEAD

Create a PR for team/AI review:

gh pr create \
  --title "docs: <epic title> スペック" \
  --label "epic,docs" \
  --body "$(cat <<'EOF'
## 概要

<!-- 1-2 sentence summary from overview.md -->

## 背景・目的

<!-- Short summary of Why + hypothesis from overview.md -->

## スペック

- `docs/specs/<epic>/overview.md`
- `docs/specs/<epic>/scope.md`

## レビュー観点

- [ ] 課題設定は妥当か
- [ ] スコープは適切か
- [ ] 完了条件は明確で検証可能か
- [ ] 見落としているリスクはないか
EOF
)"

Open in browser:

gh pr view --web

Step 6: Clean Up Worktree

Ask the user if they want to delete the docs worktree. All changes have been pushed to the remote branch, so the worktree is no longer needed.

If the user confirms:

DeleteWorktree({ branch: "docs/<epic>" })

Rules

• Always respond in the user's language
• Read existing code BEFORE asking questions
• Limit each AskUserQuestion to 2-4 questions
• Provide 2-4 concrete options per question
• Do NOT create requirements.md or design.md — that is the engineer's job (done by the recipe agent)
• Always request user confirmation after generating files

Next Step

After the PR is approved and merged, run /kitchen:order to create an Epic Issue.