manage-prd-docs

Manage PRD Docs

Discuss around product requirements, placing already effective, future-shaped, and in-progress product decisions in different lifecycle layers, and maintain a single source of authority.

Automatically advance the requirements lifecycle

When it is detected that the user is discussing, clarifying, changing, planning, implementing, or completing product requirements, immediately enter this workflow; do not wait for the user to say "discuss requirements", "write to disk", or "merge PRD".
First determine whether the requirement is shaped: the goal, scope, core requirements, and verifiable acceptance criteria are already clear, and there are no key open items that would change the product or implementation direction.
When the requirement is not yet shaped, continue the discussion and ask only questions that have a substantive impact on direction; do not block progress for low-risk details.
Once the requirement is shaped, immediately write it to disk by status: already effective behavior updates the current PRD; future requirements that have not started implementation go into docs/plans/; requirements that have started or that this round also requires implementing go into docs/work/. No longer request additional write-to-disk authorization.
Write only conclusions that are already clear; solutions still being compared, casual ideas, and content whose confirmation cannot be determined are not written for now.
Continuously sync the PRD and Todo during implementation. When the implementation, verification, and necessary documentation for this round's requirements are all complete, proactively wrap up; do not wait for the user to again say "merge PRD".
Distinguish the end of a pure discussion or PRD-writing task from implementation completion: shaped requirements that have not started remain in docs/plans/; when partially implemented, verification failed, there are blockers, or there are still open items, keep them in docs/work/。
Automatically delete only the exact working directories corresponding to this round's completed requirements. Before migrating or deleting old Phases, historical PRDs, and other temporary documents not from this round, still obtain explicit user authorization.

Identify document conventions

Locate the repository root directory, and first read the applicable AGENTS.md and repository-level instructions.
By default use the docs/under the root directory, and preferentially follow the repository's existing documentation entry points and naming conventions.
If docs/index.mdexists, first use the index to locate the current PRD, future plans, in-progress requirements, and other authoritative documents.
Read the relevant PRD, upstream and downstream plans, Todo, user documentation, README, and code contracts to avoid creating duplicate or conflicting sources of authority.
Make incremental modifications and preserve unrelated human content.

Use three layers of documentation

Divide documentation into three layers: current, future plans, and in progress:

docs/
├── index.md                 # 稳定的文档类别与生命周期导航
├── PRD.md                   # 现行产品决策与跨主题边界
├── prd/                     # 按稳定产品模块拆分的现行 PRD
│   └── <topic>.md
├── plans/                   # 已成型但尚未开始的未来需求
│   └── <requirement>/
│       ├── PRD.md
│       └── prd/             # 计划 PRD 需按主题拆分时使用
│           └── <topic>.md
└── work/                    # 仅在存在进行中需求时使用
    └── <feature-name>/
        ├── PRD.md
        ├── TODO.md
        └── prd/             # 当前需求 PRD 过长时按主题拆分
            └── <topic>.md

Do not create empty directories.
Write already effective behavior or stable commitments into the current PRD, write shaped requirements that have not started into docs/plans/, and write requirements currently being implemented into docs/work/。
When a brand-new product has not yet formed current capabilities, use docs/plans/initial-release/if implementation has not started, and use docs/work/initial-release/just for structural completeness. docs/PRD.md。
When a version is truly meaningful to users or the product, it is allowed to use plans/ and work/ with names such as <requirement>-v2 ; after completion, do not keep the version directory as a permanent historical archive.
Only v2, v3, etc. that can be independently scheduled, accepted, delayed, or canceled are maintained separately; Phases that serve only development order remain in the same in-progress PRD and Todo.
It is allowed to plan implementation stages within the in-progress PRD or Todo, but do not retain stage archives after completion.
Do not force the creation of release documentation, user documentation, or other project-specific files; when they already exist, maintain links and consistency.

Maintain the current PRD

Put docs/PRD.md Treat as the sole entry point for the product's currently effective decisions. Keep product-level scope, cross-module behavior, unified terminology, global boundaries, and module navigation in the root PRD; place the detailed current decisions of stable product modules in docs/prd/<module>.md。

Each topic retains only:

## 翻译存储与人工覆盖

- 当前决策：……
- 为什么：……
- 边界 / 非目标：……
- 权威入口：链接到用户文档、README 或源码契约。

Directly modify the old conclusions that were extended or replaced; do not append phases and let readers determine priority themselves.
Do not enumerate future plans, in-progress requirements, or other document categories in the root PRD; these belong to docs/index.md 's navigation responsibility.
The root PRD only links to module PRDs and retains cross-module decisions; do not duplicate the same decision in both the root file and module files.
Retain user behavior, product commitments, design rationale, boundaries, and non-goals that still hold.
Remove invalidated requirements, completed Todos, acceptance counts, temporary Spikes, and replaced solutions; use Git, tests, and code to trace history.
Do not duplicate API parameter tables, configuration steps, or implementation details; link to the corresponding user documentation, README, or source contract.
Do not mandate maintenance of creation dates and update dates; when a timeline is needed, use Git history or existing repository conventions.

Maintain future plans

For requirements that have taken shape and are confirmed to be retained but have not yet begun implementation, create docs/plans/<requirement>/PRD.md, using a stable English slug. Do not create plans for casual ideas, undecided solutions, or content whose retention is uncertain.

In the plan PRD, at minimum specify:

# 需求名称 v2

- 基线：当前 PRD 或另一未来计划
- 依赖：无或具体计划链接

## 背景与目标

## 新增、变更与移除

## 范围与非目标

## 验收标准

## 对后续计划的影响

Write only the incremental requirements based on the specified baseline; do not copy the complete current PRD.
When v3 depends on v2, link to the v2 plan and write only the increment based on v2.
When an upstream plan changes, is canceled, or is completed, proactively check and update the baseline, dependencies, and acceptance criteria of all downstream plans.
When a plan has not yet started, do not create TODO.md; Todos express only work that is currently being implemented.

Activate future plans

When the user begins implementing a plan:

Move the corresponding directory from docs/plans/<requirement>/ to docs/work/<requirement>/, and do not keep a PRD copy in both places.
Verify that the plan's baseline and dependencies are still valid; if upstream has not yet been completed and will block implementation, keep it in plans/ and explain the blockage.
Update the PRD to the complete currently implementable scope, and create TODO.md。
In the same change, update docs/index.md and all links pointing to the old path.

If the user requests implementation in the same round in which the requirements take shape, directly create docs/work/<requirement>/, do not first create and then move plans/ intermediate documents.

Maintain in-progress requirements

For requirements that have already begun implementation, maintain docs/work/<requirement>/, named using a stable English slug. If the requirement comes from plans/, reuse the original slug and PRD, and do not create another duplicate entry point.

In PRD.md , specify:

# 功能名称

## 背景与目标

## 范围与非目标

## 已确认需求与决策

## 验收标准

## 文档与兼容性影响

Write only verifiable confirmed content; do not write TBD, guesses, or undecided solutions.
Use TODO.md to maintain the current implementation tasks, with - [ ] and - [x] indicating status, arranged in a reasonable implementation order.
When starting implementation, do not wait for the user to issue documentation maintenance instructions; check off the Todo as each item is completed, and modify the PRD in sync when requirements change.
When requirements change, directly update the PRD and Todo to the currently effective content; do not use strikethrough to maintain a changelog within the document.
During development, completed tasks may be retained to observe progress; after requirements are finalized, delete the entire working directory.
If current product decisions have not changed, do not write the construction process into the main PRD in advance.

Maintain a stable index

Treat docs/index.md as a stable map of document categories and lifecycles, not as another PRD; treat docs/PRD.md as a map of current product modules.

When multiple document categories, future plans, in-progress requirements, or other documents exist, create docs/index.md. Once established, maintain it continuously; do not automatically delete it just because only a single PRD temporarily remains; delete it only when repository conventions change or the user explicitly requests it.
Provide the categories "current product decisions", "future plans", "in-progress requirements", and "other documents" as needed.
For current decisions, link only the root docs/PRD.md; do not enumerate the individual product modules of docs/prd/ again in the index.
List only the names, links, and baseline or dependency hints necessary for understanding the order; do not copy PRD summaries and do not record historical Phases.
When adding, activating, finalizing, canceling, deleting, renaming, or moving documents, update the index in the same change and confirm that links point to existing files.

Recommended structure:

# 文档索引

## 现行产品决策

- [产品 PRD](./PRD.md)

## 未来计划

- [团队权限 v2](./plans/team-permissions-v2/PRD.md)

## 进行中的需求

- [计费重构](./work/billing-refactor/PRD.md)

## 其他文档

- [发布流程](./release.md)

Finalized requirements

Before the end of each implementation task, proactively determine whether the corresponding requirement has been completed, without waiting for user confirmation or a finalization instruction. All Todos checked is necessary evidence, but not the only evidence. Automatically finalize only when all of the following conditions are met:

The entire scope defined by the in-progress PRD has been completed, with no valid requirements silently omitted.
Relevant tests, checks, or other reasonable verification have passed.
User documentation, APIs, configuration, or operation instructions that need to be synchronized have been updated.
All Todos are complete, and there are no blockers, failed verifications, or open issues that would affect delivery.

Once the conditions are met, immediately perform:

Compare against the in-progress PRD, implementation, tests, and user documentation to confirm there is no unhandled or still-undecided content.
Merge behavior, reasons, and boundaries that still hold long-term into docs/PRD.md or the corresponding module PRD; keep cross-module decisions in the root PRD.
Synchronize the user API, configuration, integration method, and operation instructions to their authoritative documents.
Route content that is not yet complete but still valid by status: move content that will continue to be implemented into a new work/, move content that is deferred but already formed into plans/, and do not silently discard it.
Check all future plans that depend on this requirement; change the completed upstream baseline to the current PRD, and synchronize dependencies, incremental content, and acceptance criteria.
Update docs/index.md and all affected links; do not delete an established index just because only a single PRD currently remains.
Delete the entire docs/work/<requirement>/of the completed requirement, and do not retain acceptance snapshots, completed Todos, or temporary research files.
In the final reply, inform the user of the long-term decisions that have been automatically merged, the downstream plans that have been re-reviewed, and the working directories that have been deleted.

If any condition is not met, do not assume completion; retain the working directory, update the Todos to their true status, and explain the remaining work or blockers. If whether a behavior still being implemented counts as a stable commitment would change the merge result, first ask the user to clarify.

When the user explicitly cancels a future plan, first check and update all downstream dependencies, then update the index and delete the corresponding docs/plans/<requirement>/Not only because the plan is automatically deleted if it has not started for a long time.

Migrate old Phase documents

Migrate existing phase-*, historical PRDs, or permanent Todos only after obtaining explicit user authorization:

Merge behavior, rationale, and boundaries that still hold into the current PRD.
Move valid requirements that are fully formed but not yet started to docs/plans/<requirement>/, and move those being implemented to docs/work/<requirement>/。
Move API, configuration, and usage details to their authoritative user documentation, and keep links in the PRD.
Delete completed tasks, acceptance snapshots, temporary spikes, outdated requirements, and superseded solutions.
For historical behavior that is still implemented but whose product commitment is unclear, request a decision item by item; do not silently discard it.
After confirming that the index, module navigation, plan dependencies, and links are correct, delete the old phase directories that have been absorbed.

Audit and split the PRD semantically

When a topic has an independent product boundary, can evolve or be accepted independently, has stable terminology, usually does not require understanding other topics when modified, or has already formed clear cross-module relationships, split it by module even if it is under 400 lines. Do not create small modules without semantic boundaries just to split files.

Treat 400 physical lines per PRD body file as a soft upper limit that must be audited, not as the sole trigger for splitting:

After modification, count the physical lines of the relevant PRDs.
When it reaches or exceeds 400 lines, use $file-line-audit, set the threshold to 400, and scan:
- docs/PRD.md
- docs/prd/**/*.md
- docs/plans/**/PRD.md
- docs/plans/**/prd/**/*.md
- docs/work/**/PRD.md
- docs/work/**/prd/**/*.md
First delete duplication, outdated content, and overly detailed implementation process.
If it still exceeds 400 lines after cleanup, split by domain or complete topic; do not mechanically truncate at fixed line numbers.
Place the module files of the current PRD in docs/prd/<topic>.md; the root docs/PRD.md retains the product map and cross-topic decisions.
Place topic files for future plans and in-progress requirements respectively in their prd/<topic>.md; the root PRD.md retains the requirements overview and internal navigation.
Do not create sequentially numbered files such as PRD-part-1.md、requirements-part-2.md .
Use $file-line-audit again to confirm that all PRD body files are within the upper limit.

Do not scan or split TODO.md and index.md。

Completion check

The workflow is automatically entered at the start of requirements discussion, without requiring users to remember phase passwords.
Write only requirements that are clear and fully formed, and after they are formed, automatically place them in the correct layer as active, future plan, or in progress.
docs/PRD.md Expresses only currently effective product decisions and retains cross-module decisions and module navigation.
docs/plans/ Contains only future requirements that are fully formed but not yet started; the baseline and dependencies of each plan are valid.
docs/work/ Contains only requirements that are truly in progress.
When a plan is activated, it has been moved from plans/ to work/, with no duplicate authoritative source of the PRD.
Requirements whose implementation is complete have automatically backfilled the long-term decisions, and the corresponding temporary working directories have been deleted.
Requirements that are purely under discussion, partially implemented, failed verification, or still blocked have not been prematurely closed out.
API, configuration, and usage details are in their authoritative documentation, and the PRD does not duplicate their maintenance.
docs/index.md Reflects current, future plan, in-progress, and other documents, with no broken links and no repeated enumeration of current product modules.
Stable product topics have been split by semantic boundary, with 400 lines serving only as a soft upper limit that must be audited.
Old Phase documents are not concatenated or deleted without judgment.
All PRD body files comply with the 400-line rule.