prd-generator v1.4.0A

Immutable. This exact content never changes and is served at /api/v1/blob/bb6dd0e0f88840b0.

---
name: prd-generator
description: "Generate Product Requirements Documents from `idea.md` and `validate.md` files. Use when asked to create or update a PRD. Don't use for TAD, sprint tasks, or raw idea validation."
license: MIT
effort: max
metadata:
  version: 1.4.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"
---

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

```bash
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:

```bash
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:

```bash
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.