pm-prd-write

Generate a PRD from initiative description.

Context Files

• $JAAN_CONTEXT_DIR/config.md - Configuration
• $JAAN_CONTEXT_DIR/boundaries.md - Trust rules
• $JAAN_TEMPLATES_DIR/jaan-to-pm-prd-write.template.md - PRD template
• $JAAN_LEARN_DIR/jaan-to-pm-prd-write.learn.md - Past lessons (loaded in Pre-Execution)
• $JAAN_CONTEXT_DIR/tech.md - Tech context (if exists)
• $JAAN_CONTEXT_DIR/team.md - Team context (if exists)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol

Input

Initiative: $ARGUMENTS

IMPORTANT: The initiative above is your input. Use it directly. Do NOT ask for the initiative again.

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: pm-prd-write Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Also read context files if available:

• $JAAN_CONTEXT_DIR/tech.md - Know the tech stack to reference
• $JAAN_CONTEXT_DIR/team.md - Know team structure and norms

If the file does not exist, continue without it.

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_pm-prd-write

PHASE 1: Analysis (Read-Only)

Step 1: Gather Information

You already have the initiative from the Input section above. Now ask these questions:

1. "What problem does this solve for users?"
2. "How will you measure success? (specific metrics)"
3. "What is explicitly NOT included in this scope?"
4. "Do you have design images, screenshots, or visual references to include? If yes, provide file/folder paths."

Step 2: Plan PRD Structure

After receiving answers, mentally outline:

• Title (from initiative)
• Problem Statement (from Q1)
• Success Metrics (from Q2)
• Scope boundaries (from Q3)
• User Stories (derive 3+ from context)

HARD STOP - Human Review Check

Before generating the PRD, confirm with the user:

"I have all the information needed. Ready to generate the PRD for '{initiative}'? [y/n]"

Do NOT proceed to Phase 2 without explicit approval.

PHASE 2: Generation (Write Phase)

Step 3: Generate PRD

Use the template from: $JAAN_TEMPLATES_DIR/jaan-to-pm-prd-write.template.md

Fill all sections:

• Title: From initiative
• Problem Statement: From question 1
• Solution Overview: Synthesized from input
• Success Metrics: From question 2 (table format, minimum 2)
• Scope: In-scope from input, out-of-scope from question 3
• User Stories: Derived from problem + solution (minimum 3)
• Open Questions: Any unresolved items

Image Embedding

If user provided image/screenshot paths in Step 1 Q4, embed them inline using ![description](resolved-path) in relevant sections (Solution Overview, User Stories, Appendix). Use URL-encoded paths for spaces/special characters.

Tech Context Integration

If $JAAN_CONTEXT_DIR/tech.md exists:

1. Read the file to understand tech stack
2. When generating User Stories:
   • Reference appropriate backend framework (e.g., "API endpoint in FastAPI")
   • Reference appropriate frontend framework (e.g., "React component with Redux state")
   • Reference mobile platforms if applicable
3. When generating Technical Constraints:
   • Include relevant constraints from tech.md
   • Reference specific technical requirements (e.g., "Must maintain sub-200ms p95 latency")
4. When generating Success Metrics:
   • Consider performance targets from tech.md
   • Include technical success criteria where relevant

If tech.md doesn't exist:

• Generate generic technical references
• Add note in PRD: "Update $JAAN_CONTEXT_DIR/tech.md for tech-aware PRDs"

Step 4: Quality Check

Before showing preview, verify:

• Has clear problem statement
• Has at least 2 measurable success metrics
• Has explicit out-of-scope section
• Has at least 3 user stories
• If user provided images: all references use ![alt](...) syntax with URL-encoded paths

If any check fails, revise before preview.

Step 5: Preview & Approval

Show the complete PRD and ask:

"Here's the PRD preview. Approve writing to output? [y/n]"

Step 5.5: Generate ID and Folder Structure

If approved, set up the output structure:

1. Source ID generator utility:

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"

2. Generate sequential ID and output paths:

# Define subdomain directory
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/pm/prd"
mkdir -p "$SUBDOMAIN_DIR"

# Generate next ID
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")

# Create folder and file paths
slug="{lowercase-hyphenated-from-title-max-50-chars}"
OUTPUT_FOLDER="${SUBDOMAIN_DIR}/${NEXT_ID}-${slug}"
MAIN_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-prd-${slug}.md"

3. Preview output configuration:

Output Configuration

• ID: {NEXT_ID}
• Folder: $JAAN_OUTPUTS_DIR/pm/prd/{NEXT_ID}-{slug}/
• Main file: {NEXT_ID}-prd-{slug}.md

Step 5.7: Resolve & Copy Assets

If user provided image paths in Step 1 Q4:

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/asset-embedding-reference.md for the asset resolution protocol (path detection, copy rules, markdown embedding).

Source ${CLAUDE_PLUGIN_ROOT}/scripts/lib/asset-handler.sh. For each image path: check is_jaan_path — if inside $JAAN_*, reference in-place; if external, ask user "Copy these external assets into output folder? [y/n]" and call copy_external_assets if approved. Use resolve_asset_path to get markdown-relative paths for the generated PRD.

Step 6: Write Output

1. Create output folder:

mkdir -p "$OUTPUT_FOLDER"

2. Write PRD to main file:

cat > "$MAIN_FILE" <<'EOF'
{generated PRD content with Executive Summary}
EOF

3. Update subdomain index:

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
add_to_index \
  "$SUBDOMAIN_DIR/README.md" \
  "$NEXT_ID" \
  "${NEXT_ID}-${slug}" \
  "{PRD Title}" \
  "{1-2 sentence executive summary from PRD}"

4. Confirm completion:

✓ PRD written to: $JAAN_OUTPUTS_DIR/pm/prd/{NEXT_ID}-{slug}/{NEXT_ID}-prd-{slug}.md ✓ Index updated: $JAAN_OUTPUTS_DIR/pm/prd/README.md

Step 7: Auto-Invoke User Story Generation

Use AskUserQuestion:

• Question: "Generate detailed user stories from this PRD?"
• Header: "Stories"
• Options:
  • "Yes" — Choose stories to expand
  • "No" — Skip, done with PRD only

If "No", skip to Step 8.

If "Yes":

List the user stories from the generated PRD:

"Which stories to expand into full user stories?"

[1] As a {persona}, I want {action} so that {benefit} [2] As a {persona}, I want {action} so that {benefit} [3] As a {persona}, I want {action} so that {benefit} [All] Generate all stories

Enter numbers (e.g., "1,3" or "all"):

For each selected story, run: /jaan-to:pm-story-write "{story_statement}"

This invokes the full story-write skill with INVEST validation, Gherkin acceptance criteria, and edge case mapping.

Step 8: Capture Feedback

After PRD is written, ask:

"Any feedback or improvements needed? [y/n]"

If yes:

1. Ask: "What should be improved?"
2. Offer options:

   "How should I handle this? [1] Fix now - Update this PRD [2] Learn - Save for future PRDs [3] Both - Fix now AND save lesson"

Option 1 - Fix now:

• Apply the feedback to the current PRD
• Re-run Step 5 (Preview & Approval) with updated content
• Write the updated PRD

Option 2 - Learn for future:

• Run: /jaan-to:learn-add pm-prd-write "{feedback}"
• Follow /jaan-to:learn-add workflow (categorize → preview → commit)

Option 3 - Both:

• First: Apply fix to current PRD (Option 1)
• Then: Run /jaan-to:learn-add (Option 2)

If no:

• PRD workflow complete

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Template-driven output structure
• Generic across industries and domains
• Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

• PRD file exists at correct path
• All quality checks pass
• User has approved the content
• User stories generated via /jaan-to:pm-story-write (if selected)