linsaber1012-coder/pm-prd-to-demo

PM · PRD → Demo Integrated Workflow

Turn a product idea through the full chain of "alignment → produce documentation → create clickable prototype", resulting in a dev-ready PRD, independently implementable metric definitions, and a shareable prototype that reuses the real interface of a base repository. This workflow is host-agnostic (works with Claude Code / Codex / Cursor / Gemini ), see the "Host Adaptation" section for portability details.

When to Use

• The user is acting as a Product Manager and needs to produce deliverables like PRD / metric definitions / interaction mockups;
• Typically making improvements on an existing repository or system and needs to reuse its real structure;
• Wants to simultaneously see a preliminary, clickable, shareable prototype to aid review.

Not applicable: pure coding tasks, changing only one or two lines, work with no product decision component.

What You Will Produce

1. PRD.md — the single source of truth (what to build / for whom / scope / risks / page & interaction details).
2. Metric-Definitions.md — a fully self-contained specification document; developers can implement each metric/rule by reading just this file.
3. A shareable, self-contained HTML prototype — left panel = target interface (reusing the base repo's real UI + your changes, with mock data explicitly labeled), right panel = full PRD panel.

---

Non-Negotiable Disciplines Across All Three Phases

1. Zero fabrication — everything rooted in evidence: Calibrations must trace back to source code / official docs / user confirmation; if something cannot be found, state it clearly, do not fabricate; mock data must be explicitly labeled.
2. Zero emoji: No emoji / status icons throughout the documentation and prototype; statuses are always text labels (e.g., retained / upgraded / added / untested / pending verification).
3. Write → adversarial review closed loop: For any deliverable document, first write it, then review it from the perspective of a "demanding senior PM", revise based on the issues, and loop until passed (review prompt is in prompts/reviewer-agent.md).
4. Cross-deliverable consistency: The PRD ↔ metric definitions ↔ prototype must all have consistent specifications; if orphan items or self-contradictions are found, fix them immediately.
5. Match user interaction style: Some users prefer conversation, others prefer options; if one approach is rejected, try a different one — don't force the same style.
6. Don't start writing until decisions are locked: Before producing documents, first clarify the core decisions; if goals are unclear, stop and discuss — don't guess.
7. Humanize the writing style: The document body should use natural, direct, human-like language. Actively avoid typical AI-isms (abusing dashes, "not only X, but also Y", empty parallelism / three-part template phrases, excessive hedging, over-the-top modifiers, clichés). You may load the local humanizer skill or refer to references/writing-style.md (which compiles stop-slop / Humanizer-zh / blader-humanizer). Note: technical precision where needed must still be accurate — removing AI flavor doesn't mean sacrificing accuracy or filling with fluff.

---

Phase 0 · Interactive Discovery and Decision Locking

Goal: Investigate and clarify the user's real ideas, needs, and constraints, then lock core decisions — this phase is interactive between the AI and the user; the AI does not decide for the user.

1. Scrape existing assets: Read the real structure of the repository / documentation / legacy system given by the user (if the host supports parallel exploration, scrape in parallel; otherwise, read one by one). Understand what it actually does and what can be reused.
2. Interactive requirement clarification: Use Q&A to help the user converge vague ideas into clear decisions — typical things to lock: which base repo to use, scope in/out, what metrics/features are needed, display/information architecture, explicit non-goals. Ask a few key questions at a time; don't bombard all at once.
3. Produce a decision record: Write a short "decision/planning" document summarizing the locked decisions, which serves as input for Phase 1.

Exit criteria: Each core decision has a clear answer, and the user has confirmed.

Phase 1 · Produce PRD + Metric Definitions

Goal: Produce two documents that can be handed to development.

1. Check the template: Refer to references/prd-checklist.md (a comprehensive hands-on checklist tailored to project types) to determine which sections to produce and which can be skipped for this project.
2. Write: Follow prompts/writer-agent.md to write the PRD and metric definitions. Key points:
   • PRD covers: background/goals/success metrics/scope/risks/functional structure+information architecture+flowcharts (Mermaid allowed)/detailed front-end displays and interactions per page (field-level)/glossary/global rules/stakeholders.
   • Metric definitions fully self-contained: inline all specification details; do not write "see other document" — developers can implement by reading only this file.
3. Review: Use the "senior PM" persona from prompts/reviewer-agent.md to do an adversarial review (completeness / executability / consistency between specifications and source code / scope and non-goals / risks / zero emoji / no dead links / cross-document consistency).
4. Revision loop: Fix all mandatory items from the review, then re-check until passed.
5. Checklist: Before delivery, go through references/pitfalls.md item by item (this is a checklist distilled from past mistakes).

Phase 2 · Produce a Shareable Prototype

Goal: A clickable prototype with left = target interface, right = full PRD; interface design stays true to the established source (reference mockup / base repo / competitor — see below). Strict rules are found in references/prototype-guardrails.md.

1. Determine the design source (by priority):
   • ① User provided a reference prototype / design mockup → use it as the definitive source, faithfully reproduce its visuals and layout;
   • ② Improving on an existing base repository → clone/read its frontend, extract real design tokens and layout (color scheme / light/dark / sidebar vs top bar / cards / real fields and table columns in each view), copy exactly — no improvisation;
   • ③ Neither → AI constructs from scratch, select pages from similar products / competitors as reference to create the design, and explain in the prototype which product was used as reference and why.
2. Build a self-contained HTML file: Single file, left panel = target interface (base-repo fidelity + your changes, mock data must be labeled), right panel = full PRD panel (embed the PRD inline using a minimal markdown renderer).
3. Self-contained / CSP safe: All CSS/JS inline; do not reference external CDN / fonts / icons; for anything that cannot be rendered live (e.g., certain icon libraries), honestly label the limitation and fall back to readable presentation.
4. Publish and iterate: Publish as a shareable link; when the user requests changes, update both the prototype and the PRD simultaneously to keep them in sync, and republish to the same link.

---

Pre-Delivery Checklist (Summary; see references/pitfalls.md for details)

• Zero emoji (including node labels in diagrams / code blocks)
• No fabrication: all numbers/calibrations traceable to a source; mock data labeled
• Metric definitions are fully self-contained, no "see other document" external links
• Cross-deliverable specifications consistent, no orphan items / self-contradictions
• Prototype design faithful to the established source (if reference mockup provided, follow it; if using a base repo, copy tokens exactly; if neither, reference a competitor and explain), not improvised
• Composite / aggregate scores all have explicit formulas and components
• Anything that cannot be rendered / is untested / unknown is honestly labeled, not presented as fact

---

Host Adaptation (Portability)

This SKILL.md body is host-agnostic natural language instructions that any LLM can follow. Three differences are handled outside the body:

• Loading/Invocation: See README.md for installation and invocation methods on each host (Claude Code uses the skill directory; Codex uses its skill/AGENTS.md reference; Cursor/Gemini have their own paths).
• Capability Downgrade: Where "spawn a sub-agent for review/exploration" is mentioned, if the current host does not support sub-agents, you perform the same review/exploration yourself without changing the discipline.
• Tool-Agnostic: The body only describes actions (search the web, read the repository, write files, publish a prototype) and does not bind specific tool names; each host maps them to its own tools.

Accompanying Resources

• references/prd-checklist.md — PRD component list + tailoring by project type
• references/prototype-guardrails.md — Prototype hard rules
• references/pitfalls.md — Pitfall checklist
• references/writing-style.md — De-AI-ification / humanized writing rules (compiling stop-slop / Humanizer-zh / blader-humanizer + local humanizer skill)
• prompts/writer-agent.md — Writer agent prompt template
• prompts/reviewer-agent.md — Senior PM reviewer agent persona + checklist
• templates/prd-skeleton.md / templates/metric-spec-skeleton.md — Skeleton templates