project-prd-doc-builder

Build complete PRD documentation based on the project directory

This skill transforms an existing project directory intoa trustworthy, clearly structured, and maintainable product requirements document (PRD) and comprehensive documentation site. By default, it uses progressive disclosure: first establish a global understanding, then explain the business landscape and scenarios, and finally go into features, rules, data, interactions, architecture, and acceptance details. The site style references VitePress and supports Markdown, Mermaid, C4 diagrams, interactive flows, prototypes, and standalone page embedding.

Use When

• The user asks to create/rewrite a complete PRD based on an existing codebase, project folder, historical documents, user stories, architecture diagrams, or test content.
• The user wants to organize scattered materials into a readable, searchable, cross-linkable comprehensive documentation site.
• It is necessary to identify the current state from the implementation while clearly separating target behavior, user needs, business rules, and acceptance criteria.
• It is necessary to plan which diagrams each chapter uses, including business process diagrams, swimlane diagrams, user journeys, use case relationship diagrams, sequence diagrams, state diagrams, data models, and C4 architecture diagrams.
• It is necessary to deliver documentation that can be read statically, reviewed, and archived, and can also embed interactive flows or prototypes.

Don't Use When

• The user only asks to fix copy or translate a passage of text, and it does not involve project discovery or PRD structure.
• The user explicitly wants only a single-page summary, marketing copy, or documentation for one specific API; the delivery scope should be narrowed, and a full site should not be generated automatically.
• The user asks to design a brand-new product from scratch without a project directory as a basis; in this case, a product planning process may be used, but assumptions must be marked as assumptions.
• The user asks to directly modify business code rather than produce documentation; do not treat the PRD skill as a code refactoring skill.

Workflow

1. Confirm delivery boundaries and inspect the existing structure

1. First read the repository root directory, existing documentation directory, README, project description, user stories, architecture diagrams, data models, configuration files, and tests.
2. Identify whether VitePress, Docusaurus, MkDocs, Storybook, a prototype site, or a documentation publishing process already exists. Prefer extending the existing system and do not overwrite existing configuration.
3. Identify the scope, target readers, product stage, and delivery format explicitly proposed by the user. When non-critical details are missing, adopt conservative defaults and record assumptions; do not interrupt work over minor issues.
4. Treat the existing code as "evidence of the current implementation," and do not directly equate implementation details with "correct requirements."

2. Establish a project evidence ledger

1. According to project discovery and evidence strategy , inventory the content and establish an evidence list.
2. For each important conclusion, indicate the source, evidence type, and confidence level; distinguish confirmed facts, reasonable inferences, conflicts, and open questions.
3. Prefer authoritative materials within the repository. Processes, business rules, performance metrics, permission behavior, and exception handling without evidence must not be written as established facts.
4. Do not copy secrets, tokens, personal data, production credentials, or unnecessary sensitive content into the documentation.

3. Reconstruct the product and business model

1. First extract the product goals, user roles, core objects, system boundaries, external systems, main business outcomes, and non-goals.
2. Draft the end-to-end main business process, then break it down into stage processes, user stories, use cases, decision points, state transitions, and exception paths.
3. Clearly distinguish between "As-Is", "To-Be", and "Open"; if the user has not specified, do not assume the current code is the target experience.
4. Ensure every key stage has inputs, processing, outputs, responsible roles, success conditions, and exception exits.

4. Plan a progressive information architecture

Follow the PRD information architecture to arrange the sections:

1. Product overview: let readers quickly understand what the product is, what problem it solves, and whom it serves.
2. Business overview: use one end-to-end diagram to clearly explain business goals and stage relationships.
3. Core scenarios: use user stories and use cases to explain who does what under what conditions and what results they get.
4. Detailed specifications: then expand into functional requirements, business rules, data, states, UX, interfaces, and non-functional requirements.
5. Acceptance and delivery: clarify acceptance conditions, test coverage, requirements traceability, risks, and version strategy.

At the beginning of each page, use a brief "what problem does this page solve" or summary to explain its positioning. Avoid piling up implementation details on the homepage, and avoid cramming all content into one overly long Markdown document.

5. Choose appropriate diagrams for each chapter

Based on the diagram and Mermaid/C4 standards , establish a diagram list and use diagrams according to actual complexity. Each diagram must have a purpose, boundary, figure number, description, related requirement IDs, and maintenance responsibility.

• Overall business process: provide a standalone, readable static main process; for complex processes, an interactive layered browser may also be provided.
• Stage/cross-role processes: use swimlane-style flowcharts or stage responsibility tables.
• Multi-role goals: user story maps or use case diagrams; simple scenarios can use tables.
• Multi-system interactions: sequence diagrams; complex entity lifecycles: state diagrams.
• Domain objects and relationships: ER diagrams or domain model diagrams.
• System boundaries: C4 System Context; system deployment units: C4 Container; only continue to draw Component diagrams for complex containers.
• Each diagram should express only one main issue; split diagrams when they are too complex, and do not use "many diagrams" as a substitute for completeness.

6. Write executable requirements

1. Use stable, unique IDs:US-*、UC-*、FR-*、BR-*、DATA-*、STATE-*、FLOW-*、DIA-*、AC-*、NFR-*、API-*。
2. User stories express user value; use cases express interaction flows; functional requirements express observable system behavior; business rules express decisions/constraints; acceptance criteria express verifiable results. These types must not be mixed into one vague description.
3. For important requirements, write preconditions, triggers, main paths, alternative/exception paths, inputs and outputs, permissions, state impacts, and testable acceptance criteria.
4. For algorithms, optimizers, AI, or automation capabilities, explain inputs, outputs, constraints, goals, failure/timeout fallbacks, manual adjustment methods, and explainability requirements; do not promise optimality or performance out of thin air.
5. For detailed formats, see How to write requirements, use cases, and acceptance criteria。

7. Establish a documentation site and embedding capability

1. If the repository already has a documentation site, continue its tech stack and theme; if it does not and the user wants a comprehensive documentation site, prioritize creating a separate VitePress documentation directory to avoid conflicts with the application build configuration.
2. Adopt the interactive documentation site conventions, unifying the specifications for directories, navigation, sidebars, page templates, and embedded content.
3. Write plain text/tables in Markdown; use Mermaid for native diagrams; write lightweight interactions as Vue components; for complex prototypes or 3D pages, use independent routes/HTML/iframe, retaining a static summary or fallback link.
4. Dynamic flows must not become the sole source of truth: always retain a static main flow that can be read independently, textual branch descriptions, and archivable source files.

8. Establish traceability relationships and perform automated validation

1. Link user stories, use cases, functional requirements, business rules, diagrams, pages/components, test scenarios, and acceptance criteria together.
2. Place unknown items in the "Open Questions" table and mark the requirements and decisions they affect; do not use "to be confirmed" to replace content that can already be derived from evidence.
3. Run scripts/validate_prd.py <文档目录> to check Markdown links, duplicate IDs, unclosed Mermaid code blocks, obvious placeholders, and basic structural issues.
4. If the environment permits, perform documentation site installation/build and Mermaid rendering checks; if not performed, state this explicitly and do not claim the build passed.
5. Complete the review according to Quality Gates and Delivery Checklist .

9. Delivery and Summary

Final explanation: documentation output location, main pages, diagrams and embedded components, evidence coverage, important assumptions/conflicts, automated validation results, and items not yet verified. Do not deliver only a directory tree or a plan; actually create the files and inspect the artifacts.

Rules

• Reconnaissance must precede writing. Do not guess the entire product from directory names, and do not treat the first README as the sole source of truth.
• Progressive disclosure is required. Move from the global to scenarios and then to details; provide a main diagram for important flows, and expand complex logic through subpages/collapsing/interactions.
• Evidence and design recommendations must be distinguished. Explicitly mark unknown information and do not disguise inferences as facts.
• Both product and technical readers must be accommodated. Product readers can understand the business value and operational flows; engineering readers can find requirement IDs, statuses, data, boundaries, and acceptance evidence.
• Diagrams must be incorporated into documentation governance. Every key diagram has a name, purpose, unique ID, source, related requirements, and update conditions.
• Static reading must be supported. Key business logic must not exist only in animations, interactive components, or remote iframes.
• Verifiable acceptance criteria must be used. Prefer given/action/result or explicit numerical thresholds; place thresholds without a basis in the open questions.
• Existing engineering must be respected. Do not overwrite existing site configuration, install dependencies without authorization, modify production business code, or mix documentation generation and business implementation in the same batch of changes.
• Generating false completeness is prohibited. Do not fabricate interfaces, role permissions, SLAs, algorithm accuracy, regulatory commitments, or external system behavior.
• Outputting only isolated long-form text is prohibited. Unless the user explicitly requests a single file, use a multi-page structure with navigation, cross-links, attachments, and a diagram index.
• Mechanically adding diagrams to every chapter is prohibited. Use tables/text when they are clearer; add diagrams only when they reduce comprehension cost.
• Do not cram all details into SKILL.md. Read the following reference files as needed to keep the process executable and avoid unnecessary context usage.

Examples

• "Write a complete PRD based on this project directory" → Survey the code and materials, create a multi-page PRD documentation site, flowcharts, use cases, requirements, and acceptance criteria, and maintain an evidence ledger.
• "Organize user stories, architecture diagrams, and source code into a VitePress documentation site" → After checking the existing site, extend it or create a standalone VitePress site, embedding Mermaid/C4 and interactive components.
• "First turn the overall business process into an expandable dynamic diagram" → Deliver both a static main process and stage sub-processes, node metadata, and interactive components; keep the static and interactive content consistent.
• "Help me reverse-engineer and complete the requirements from the existing code" → Treat the source code and tests as evidence of the current state, list the parts that conflict with the existing documentation, and distinguish implemented features from target requirements.

Edge Cases

• The project directory is very large: First use the directory tree, search, and dependency lists to locate high-value files; sample by module, then go deep on key processes; do not indiscriminately read node_modules, build artifacts, binaries, or generated files.
• Documentation conflicts with code: Keep a record of the conflict and explain what conclusions each side supports; do not silently overwrite either side.
• Only source code, no business description: First form "current behavior inferred from the implementation" and its confidence level, then list the target behavior as pending product confirmation. A draft may be delivered, but it must not be disguised as a final version.
• Only business documentation, no source code: Write the requirements based on the business materials; mark technical feasibility, implementation status, and interface details as unverified.
• An old version of the PRD exists in the project: Determine which sections are still valid and which are outdated; clearly state what is retained, replaced, and deprecated in the change log; do not assume the old document is entirely correct by default.
• Some information is missing: If it does not block output, adopt conservative assumptions and enter them into the assumptions ledger; if it could change the product boundary or core workflow, prioritize giving the most reasonable annotated version rather than stopping all work.
• The site is not suitable for adding complex frontend: Use Markdown + Mermaid + static export as the baseline, and make interactive features optional enhancements.
• Node or Python cannot be run: Complete file generation and perform an executable static review; accurately report the checks that were not performed.
• The project materials contain sensitive information: Do not copy keys, production accounts, customer personal information, access tokens, or internal private URLs verbatim into public documentation; abstract or redact them when necessary.

References

Read on demand according to the task; it is not required to load all reference documents at once every time:

• Project survey and evidence strategy: directory discovery, evidence grading, conflict and inference management.
• PRD information architecture: recommended directory, section purposes, and progressive disclosure order.
• How to write requirements, use cases, and acceptance: ID rules, templates, acceptance, and traceability relationships.
• Diagram and Mermaid/C4 standards: diagram decisions for each chapter, process layering, and boundaries for using C4.
• Interactive documentation site conventions: VitePress organization, embedding categories, security, and fallback.
• Quality gates and delivery checklist: readability, coverage, publishing, and final checks.

A copyable template is located at assets/. After generation, use scripts/validate_prd.py to validate the document directory.