product

/product — Interactive PRODUCT.md Generation

Purpose: Guide the user through creating a PRODUCT.md that unlocks product-aware reviews in /pre-mortem and /vibe, including the default quick-mode inline paths.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

CLI dependencies: None required.

Execution Steps

Given /product [target-dir]:

• target-dir defaults to the current working directory.

Step 1: Pre-flight

Check if PRODUCT.md already exists:

ls PRODUCT.md 2>/dev/null

If it exists:

Use AskUserQuestion:

• Question: "PRODUCT.md already exists. What would you like to do?"
• Options:
• "Overwrite — start fresh" → continue to Step 2
• "Update — keep existing content as defaults" → read existing file, use its values as pre-populated suggestions in Step 3
• "Cancel" → stop, report no changes

If it does not exist: continue to Step 2.

Step 2: Gather Context

Read available project files to pre-populate suggestions:

1. README.md — extract project description, purpose, target audience
2. package.json / pyproject.toml / go.mod / Cargo.toml — extract project name
3. Directory listing — ls the project root for structural hints
4. Existing product/release docs — if present, read PRODUCT.md, GOALS.md, release notes, comparison docs, and recent .agents/research/ or .agents/plans/ artifacts for PMF, positioning, and evidence context

Use what you find to draft initial suggestions for each section. If no files exist, proceed with blank suggestions.

Step 3: Interview

Ask the user about each section using AskUserQuestion. For each question, offer pre-populated suggestions from Step 2 where available.

3a: Mission

Ask: "What is your product's mission? (One sentence: what does it do and for whom?)"

Options based on README analysis:

• Suggested mission derived from README (if available)
• A shorter/punchier variant
• "Let me type my own"

3b: Target Personas

Ask: "Who are your primary users? Describe 2-3 personas."

For each persona, gather:

• Role (e.g., "Backend Developer", "DevOps Engineer")
• Goal — what they're trying to accomplish
• Pain point — what makes this hard today

Use AskUserQuestion for the first persona's role, then follow up conversationally for details and additional personas. Stop when the user says they're done or after 3 personas.

3c: Core Value Propositions

Ask: "What makes your product worth using? List 2-4 key value propositions."

Options:

• Suggestions derived from README/project context
• "Let me type my own"

3d: Competitive Positioning

Ask: "What alternatives exist, and how do you differentiate?"

Gather for each competitor:

• Alternative name
• Their strengths (where they win)
• Your differentiation (where you win)
• Feature-level comparison (specific capabilities, not just vibes)

Then ask: "What is the market trend you're betting on that competitors are ignoring?"

This produces the Strategic Bet section — the contrarian thesis that justifies your product's existence. Examples:

• "We bet that AI agents will need institutional memory, not just prompts"
• "We bet that local-first tools will win over cloud-dependent ones"

If the user says "none" or "skip" for competitors, write "No direct competitors identified" but still ask about the strategic bet.

3e: Evidence (Traction + Impact)

Ask: "What evidence do you have that this product works?"

Gather what's available:

• Usage data — stars, downloads, clones, active users, installs
• Measured impact — bugs caught, time saved, regressions prevented, outcomes achieved
• User feedback — testimonials, retention signals, community activity

Auto-gather if possible:

• If the project has a GitHub remote, pull real metrics: gh api repos/{owner}/{repo} --jq '{stars: .stargazers_count, forks: .forks_count, open_issues: .open_issues_count}'
• If .agents/ exists, count learnings, council verdicts, and retros as usage evidence
• If GOALS.md exists, pull fitness score as a quality metric

If the project is new with no evidence yet, write "Pre-traction — evidence to be gathered" and list what metrics to track.

3f: Known Product Gaps

Ask: "What's broken, missing, or embarrassing about the product right now? Be honest."

This section is the most valuable one for internal product docs. It prevents the doc from being marketing copy. Gather:

• Missing capabilities — features users ask for that don't exist
• Broken promises — things the README claims that don't fully work
• Onboarding friction — where new users get stuck
• Technical debt — known limitations that affect product quality

If the user says "nothing", gently challenge: "Every product has gaps. What would a frustrated user complain about?" Push for at least 2 honest gaps.

3g: Product Sense Pass

Ask: "What would give your target audience a 10-star experience?"

Use this as a mandatory product judgment pass. Do not name-drop frameworks in the final document unless useful; translate them into concrete product decisions.

For each lens, gather or infer the answer:

| Lens | Question to answer | Output it should shape | |------|--------------------|------------------------| | Chesky 10/11-star experience | What would make the first meaningful use feel unexpectedly great, not merely functional? | 10-Star Experience section and first-value path. | | Rahul Vohra / Superhuman PMF | Which narrow segment would be very disappointed if this disappeared? Who should we ignore for now? | PMF Wedge, target personas, and anti-personas. | | April Dunford positioning | What is the real alternative, where does it win, and what context makes this product obviously better? | Competitive positioning and strategic bet. | | Teresa Torres discovery | What recurring customer touchpoints or experiments will keep this honest? | Evidence and discovery metrics. | | Marty Cagan outcomes | What user/business outcome matters beyond shipped features? | Core value propositions and known gaps. | | Gibson Biddle DHM | How does the product delight users in ways that are hard to copy and sustainable to keep improving? | Product strategy and moat. | | Elena Verna PLG | Can the user reach value without human glue or heavy setup? Where is friction too high? | 10-star experience and onboarding gaps. | | Melissa Perri build-trap guardrail | Are we listing features or making strategic choices tied to target conditions? | Product strategy and prioritization. | | Shreyas Doshi product sense | What motivation, friction, satisfaction, and nudges decide whether usage repeats? | Value props, activation, and retention loop. |

Capture:

• PMF wedge: the narrow segment to optimize for now
• Anti-personas: who the product should not optimize for yet
• 10-star first experience: the user's first 30-60 minutes, step by step
• Retention loop: what makes the next session or next use better
• Moat: what becomes harder to copy over time
• Friction: the setup or comprehension costs that would kill adoption

3h: Validated Principles (Auto-discovered)

Do not ask the user. Scan the project for extracted principles:

1. Check .agents/planning-rules/ — compiled planning principles
2. Check .agents/patterns/ — battle-tested patterns from usage
3. Check .agents/learnings/ — accumulated learnings

If any exist, count them and note their source (e.g., "7 planning rules extracted from 544K agent messages"). These will be included in the output as "Validated Principles" — principles proven through usage, not just design assumptions.

If none exist, skip this section in the output.

Step 4: Generate PRODUCT.md

Write PRODUCT.md to the target directory with this structure:

---
last_reviewed: YYYY-MM-DD
---

# PRODUCT.md

## Mission

{mission from 3a}

## Vision

{one-sentence aspirational framing — what the world looks