$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:

Ask the user directly:

• 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. 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

Ask the user 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:

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 like if the product succee