luongnv89/prd-generator

PRD Generator

Generate comprehensive Product Requirements Documents from validated idea files.

Repo Sync Before Edits (mandatory)

Before creating/updating/deleting files in an existing repository, sync the current branch with remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If origin is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Input

Preferred: project folder path in $ARGUMENTS containing:

• idea.md - Product concept and technical context (required)
• validate.md - Evaluation and recommendations (required)

If path is not provided (auto-pick mode):

1. Reuse the most recent project folder path from this chat/session (typically from idea-validator output).
2. If unavailable, use env var IDEAS_ROOT when present.
3. Else check shared marker file ~/.config/ideas-root.txt.
4. Backward compatibility fallback: ~/.openclaw/ideas-root.txt.
5. If still unavailable, ask the user to provide the path or set IDEAS_ROOT.
6. If multiple candidates are plausible, ask user to choose.

Workflow

Mode selection (decide before Phase 1): If PROJECT_DIR/prd.md already exists and the user wants changes to it, this is a modify run — do Phase 1's steps 1-4 (including the mandatory backup), then skip to ## Modification Mode below instead of Phases 2-5, rejoining the workflow at Phase 6. Otherwise this is a create run — proceed through Phases 1-7 in order. Both modes share Phase 1's backup step; see ## Modification Mode for modify-run detail.

Phase 1: Validate Input

1. Resolve PROJECT_DIR (from $ARGUMENTS or auto-pick mode above)
2. Check PROJECT_DIR/idea.md exists
3. Check PROJECT_DIR/validate.md exists
4. If PROJECT_DIR/prd.md exists, create backup: prd.backup.YYYYMMDD_HHMMSS.md

Phase 2: Extract Context

From idea.md:

• Product name/concept
• Target audience
• Goals & objectives
• Technical context (stack, constraints)

From validate.md:

• Verdict and ratings
• Strengths/weaknesses
• Competitors
• Enhanced version suggestions
• Implementation roadmap

Phase 3: Clarify Requirements

Ask user (if not clear from input files):

• Official product name?
• Business model? (SaaS, marketplace, freemium)
• Target MVP timeframe?
• Team size/composition?
• Compliance requirements? (GDPR, HIPAA, SOC2)

Phase 4: Generate PRD

Create prd.md with these sections:

1. Product Overview - Vision, users, objectives, success metrics
2. User Personas - 2-3 detailed personas from target audience
3. Feature Requirements - Matrix with MoSCoW prioritization, user stories, acceptance criteria
4. User Flows - Primary flows with mermaid diagrams
5. Non-Functional Requirements - Performance, security, compatibility, accessibility
6. Technical Specifications - Architecture diagram, frontend/backend/infrastructure specs
7. Analytics & Monitoring - Key metrics, events, dashboards, alerts
8. Release Planning - MVP and version roadmap with checklists
9. Open Questions & Risks - Questions, assumptions, risk mitigation
10. Appendix - Competitive analysis, glossary, revision history

Read references/prd-template.md for the full template structure.

Phase 5: Output

1. Write prd.md to project folder
2. Summarize sections created
3. Highlight areas needing user review
4. Suggest next steps

Phase 6: README Maintenance (ideas repo)

After writing prd.md, if the project folder is inside an ideas repo, update the repo README ideas table:

• Preferred: cd to the repo root and run python3 scripts/update_readme_ideas_index.py (if it exists)
• Fallback: update README.md manually (ensure PRD status becomes ✅ for that idea)

Phase 7: Commit and push

• Commit immediately after updates.
• Confirm before pushing — this is a visible action:

git push origin <branch>

• If push is rejected: git fetch origin && git rebase origin/main && git push.

Step Completion Reports

After completing each major step, output a status report in this format:

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Adapt the check names to match what the step actually validates. Use √ for pass, × for fail, and — to add brief context. The "Criteria" line summarizes how many acceptance criteria were met. The "Result" line gives the overall verdict.

Per-phase check names and the full set of seven templates (one for each of Phases 1-7) live in references/step-reports.md — read it before emitting the first report.

Reporting with GitHub links (mandatory)

When reporting completion, include:

• GitHub link to prd.md
• GitHub link to README.md when it was updated
• Commit hash

Link format (derive <owner>/<repo> from git remote get-url origin):

• https://github.com/<owner>/<repo>/blob/main/<relative-path>

Modification Mode

Entered per the Mode selection note above, once Phase 1's backup (prd.backup.YYYYMMDD_HHMMSS.md) already exists:

1. Ask what to modify (features, priorities, timeline, specs, personas)
2. Apply changes preserving structure
3. Update revision history

Guidelines

• Thorough: Cover all sections comprehensively
• Realistic: Base on validate.md feasibility ratings
• Specific: Include concrete metrics and criteria
• Actionable: Every section guides implementation
• Visual: Include mermaid diagrams for architecture and flows

Acceptance Criteria

A run is considered successful only when every item below is verifiable in the produced prd.md. Use these as a checklist; reject and regenerate the section if any check fails.

• [ ] prd.md is written to PROJECT_DIR (same folder as idea.md).
• [ ] File contains all 10 top-level sections (verify with grep -c '^## ' returns >= 10): Product Overview, User Personas, Feature Requirements, User Flows, Non-Functional Requirements, Technical Specifications, Analytics & Monitoring, Release Planning, Open Questions & Risks, Appendix.
• [ ] Product Overview cites the source idea.md (explicit phrase like "Source: idea.md" or quoted concept text from idea.md).
• [ ] Success Metrics subsection lists at least 3 metrics, each with a measurable target (number + unit + timeframe, e.g. "DAU >= 1000 within 90 days post-launch").
• [ ] User Personas section contains 2-3 persona blocks; each persona has Name, Role, Goals, Pain Points, and a representative quote.
• [ ] Feature Requirements use MoSCoW labels (Must, Should, Could, Won't) and at least 5 items total.
• [ ] Each Must/Should feature has at least one acceptance criterion in Given <context> / When <action> / Then <outcome> format (verify with grep -E "Given .* When .* Then").
• [ ] User Flows section contains at least one fenced ```mermaid block with valid flowchart or sequenceDiagram syntax.
• [ ] Non-Functional Requirements lists numeric targets for performance (e.g. p95 latency, throughput) and at least one security/privacy requirement.
• [ ] Open Questions & Risks lists at least 3 risks, each with likelihood, impact, and mitigation.
• [ ] Appendix.Revision History records this generation event with date and "v1.0 — initial PRD".
• [ ] If a previous prd.md existed, a prd.backup.YYYYMMDD_HHMMSS.md sibling file was written before overwrite.
• [ ] Step Completion Reports are emitted for phases 1-7 with Result: PASS (or explicit PARTIAL/FAIL with reason).

Always verify the checklist explicitly in the final completion report (echo each item with √ or ×).

Expected Output

The generated prd.md follows a fixed 10-section skeleton (Product Overview, Personas, Feature Requirements, User Flows, NFRs, Tech Specs, Analytics, Release Planning, Risks, Appendix) with a header citing Source: idea.md, validate.md and a final console summary line. See references/expected-output.md for the full skeleton and console summary template.

Edge Cases

Handle missing inputs, verdict=REJECT, conflicting requirements, existing PRDs (always backup), unclear tech/compliance context, and Mermaid validation failures. See references/edge-cases.md for the full list and required behaviour.

Verification Steps

Run the grep-backed thresholds listed under ## Acceptance Criteria above (heading count, mermaid block, Given/When/Then, MoSCoW count, idea.md citation, backup sibling). See references/verification-steps.md for the exact shell commands to run each check.