MartinoPolo/mp-requirements-to-prd

Write PRD

Create a Product Requirements Document as a GitHub issue from REQUIREMENTS.md. $ARGUMENTS

Workflow

Step 1: Read Requirements

# From project root

Read .mpx/REQUIREMENTS.md. If missing, report error and stop.

Step 2: Explore Codebase

Understand current project state:

• Read package.json for project name, dependencies, scripts
• Glob for key structural files (src/, lib/, etc.)
• Read existing README or docs for context
• Note existing patterns, frameworks, conventions

Step 3: Design Modules

Sketch out the major modules needed for this feature:

• Identify the key modules/components the implementation requires
• Look for opportunities to extract deep modules (simple interface hiding extensive implementation)
• Confirm modules match user expectations and determine which modules need tests

Ask: "Here is the proposed module breakdown. Does this match your expectations? Which modules need tests?"

Incorporate feedback before proceeding to the draft.

Step 4: Draft PRD

Build the PRD with these sections:

Overview

What this is and why it matters. Tie back to REQUIREMENTS.md.

User Stories

For each requirement, write:

As a [user], I want [action], so that [benefit]

Scope

• Included: features and deliverables explicitly in requirements
• Excluded: what is intentionally out of scope

Acceptance Criteria

Measurable, testable criteria for each user story. Use checkbox format:

• [ ] Criterion 1
• [ ] Criterion 2

Technical Notes

• Architecture constraints
• Dependencies and version requirements
• Known risks or open questions

Implementation Decisions

• Modules, interfaces, architectural decisions
• Schema changes, API contracts
• Specific interactions between components
• NO file paths or code snippets

Testing Decisions

• What makes good tests for this feature
• Which modules need tests (from Step 3)
• Prior art in the existing test suite
• Test boundaries

Step 5: Get Approval

Show the full PRD draft to the user:

Ask: "Here is the PRD draft. Approve, or describe edits?"

Incorporate any requested edits. Re-show if changes are substantial.

Step 6: Create Label

Ensure the prd label exists:

gh label create prd --description "Product Requirements Document" --color 0052CC --force

Step 7: Find Next PRD Number

List existing PRD issues to determine the next sequential number:

gh issue list --label prd --state all --json title --jq '.[].title'

Parse titles for PRD-N: prefix, find the highest N, increment by 1. If no PRDs exist, start at 1.

Step 8: Create Issue

gh issue create --title "PRD-<N>: [title from requirements]" --label "prd" --body "$(cat <<'EOF'
[PRD body from Step 4]
EOF
)"

Step 9: Assign Milestone

If $ARGUMENTS contains a milestone name:

gh issue edit <number> --milestone "<milestone name>"

Skip if no milestone provided.

Step 10: Report

Display:

• Issue URL
• Issue number
• Title
• Milestone (if assigned)

Rules

• Always read REQUIREMENTS.md first — the PRD must trace back to requirements
• Show the PRD to the user before creating the issue
• Use gh CLI for all GitHub operations
• PRD body must be well-formatted GitHub markdown
• Never create the issue without user approval