product-implement

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

product-implement

What this skill does

这个 skill 的作用

Transforms accepted PDRs into a comprehensive, self-contained

PRD.md

using a three-phase DAG:

Plan Agent: Analyze PDRs, detect feature-areas, generate customized DAG, get user approval
Execute Agent: Generate sections per feature-area with mandatory checkpoint after Requirements
Summarize Agent: Aggregate sections, resolve conflicts, produce unified
```
PRD.md
```

Output:

```
docs/adlc/product/PRD.md
```
— self-contained product requirements (the shared layout; legacy repo-root
```
PRD.md
```
stays read-compatible)

{REPO_ROOT}/.adlc/product/sections/{feature-area}/{section}.md

— intermediate section files

Accepted PDRs moved to
```
{REPO_ROOT}/docs/adlc/memory/pdr/
```
(the shared layout canonical memory root)

通过 三阶段 DAG，将 已接受的 PDR 转换为内容全面且自包含的

PRD.md

：

Plan Agent：分析 PDR，检测功能域，生成定制 DAG，并获得用户批准
Execute Agent：按功能域生成各章节，并在 Requirements 后强制设置检查点
Summarize Agent：汇总章节、解决冲突，生成统一的
```
PRD.md
```

输出：

```
docs/adlc/product/PRD.md
```
— 自包含的产品需求文档（采用共享目录结构；仓库根目录下旧版
```
PRD.md
```
仍可读取）

{REPO_ROOT}/.adlc/product/sections/{feature-area}/{section}.md

— 中间章节文件

将 已接受的 PDR 移动至
```
{REPO_ROOT}/docs/adlc/memory/pdr/
```
（共享目录结构的标准 memory 根目录）

When to use

何时使用

After
```
/product-clarify
```
has approved PDRs
After
```
/product-init
```
to document existing product
PDR updates requiring PRD regeneration

在
```
/product-clarify
```
已批准 PDR 后
在
```
/product-init
```
后为现有产品编写文档
需要重新生成 PRD 的 PDR 更新

When NOT to use

何时不应使用

No Accepted PDRs (run
```
/product-clarify
```
first)
Minor PRD edits (edit
```
PRD.md
```
directly)

没有已接受的 PDR（先运行
```
/product-clarify
```
）
PRD 的小幅修改（直接编辑
```
PRD.md
```
）

Pre-Flight Validation

预检验证

Before starting, verify prerequisites:

Check PDRs exist:
```
{REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md
```
Check for Accepted PDRs: Count files with status "Accepted"
- If zero: STOP and output:
```
Cannot proceed: No Accepted PDRs found.
Run /product-clarify to review and approve PDRs first.
```
- If ≥1: Proceed

开始前，验证前置条件：

检查 PDR 是否存在：
```
{REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md
```
检查是否存在已接受的 PDR：统计 status 为 "Accepted" 的文件
- 如果为零：停止并输出：
```
Cannot proceed: No Accepted PDRs found.
Run /product-clarify to review and approve PDRs first.
```
- 如果 ≥1：继续

Three-Phase DAG Workflow

三阶段 DAG 工作流

┌─────────────────────────────────────────────────────────┐
│ PHASE 1: PLAN (Plan Agent)                              │
│ Load PDRs → Detect Feature-Areas → Generate DAG → Approve│
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ PHASE 2: EXECUTE (Execute Agent)                        │
│ Overview → Problem → Goals → Metrics → Personas         │
│ → [REQUIREMENTS CHECKPOINT] ← MANDATORY USER APPROVAL   │
│ → NFRs → Out-of-Scope → Risks → Roadmap → PDR-Summary   │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ PHASE 3: SUMMARIZE (Summarize Agent)                    │
│ Read sections → Detect conflicts → Resolve → PRD.md     │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ PHASE 1: PLAN (Plan Agent)                              │
│ Load PDRs → Detect Feature-Areas → Generate DAG → Approve│
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ PHASE 2: EXECUTE (Execute Agent)                        │
│ Overview → Problem → Goals → Metrics → Personas         │
│ → [REQUIREMENTS CHECKPOINT] ← MANDATORY USER APPROVAL   │
│ → NFRs → Out-of-Scope → Risks → Roadmap → PDR-Summary   │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ PHASE 3: SUMMARIZE (Summarize Agent)                    │
│ Read sections → Detect conflicts → Resolve → PRD.md     │
└─────────────────────────────────────────────────────────┘

Execution Steps

执行步骤

Phase 1: Plan

阶段 1：规划

Step 1.1: Load and Analyze PDRs

Read all
```
PDR-*.md
```
files from
```
.adlc/drafts/pdr/
```
Filter to Accepted status only
Parse feature-area from each PDR
Group PDRs by feature-area

Step 1.2: Detect Feature-Area Characteristics

Characteristic	Detection Pattern	DAG Customization
B2B SaaS	Enterprise, admin, SSO	Include compliance sections
Consumer App	Mobile, freemium, social	Simplify requirements
Platform	API, integrations, developer	Expand NFRs
Marketplace	Multi-sided, transaction	Add business model sections

Step 1.3: Generate Customized DAG

Default DAG (all 15 sections):

Document Information → Executive Summary → Overview → Problem
→ Market Opportunity → Goals → Metrics → Personas
→ [CHECKPOINT: Requirements]
→ NFRs → Out-of-Scope → Risks → Investment
→ Roadmap → Go-to-Market → PDR-Summary

Section numbering (fixed):

1. Document Information
1.5 Executive Summary
1. Overview
1. The Problem
3.5 Market Opportunity
1. Goals & Objectives
1. Success Metrics
1. Personas
1. Functional Requirements
1. Non-Functional Requirements
1. Out of Scope
1. Risks & Mitigation
10.5 Investment & Resources
1. Roadmap & Milestones
11.5 Go-to-Market Strategy
1. PDR Summary

Step 1.4: Present Plan for Approval

markdown

undefined

步骤 1.1：加载并分析 PDR

从
```
.adlc/drafts/pdr/
```
读取所有
```
PDR-*.md
```
文件
仅筛选 status 为 Accepted 的文件
从每个 PDR 解析所属功能域
按功能域对 PDR 分组

步骤 1.2：检测功能域特征

特征	检测模式	DAG 定制方式
B2B SaaS	企业、管理员、SSO	包含合规章节
消费者应用	移动端、免费增值、社交	简化需求
平台	API、集成、开发者	扩展 NFR
Marketplace	多边、交易	添加商业模式章节

步骤 1.3：生成定制 DAG

默认 DAG（全部 15 个章节）：

Document Information → Executive Summary → Overview → Problem
→ Market Opportunity → Goals → Metrics → Personas
→ [CHECKPOINT: Requirements]
→ NFRs → Out-of-Scope → Risks → Investment
→ Roadmap → Go-to-Market → PDR-Summary

章节编号（固定）：

1. 文档信息
1.5 执行摘要
1. 概述
1. 问题
3.5 市场机会
1. 目标与目的
1. 成功指标
1. 用户角色
1. 功能需求
1. 非功能需求
1. 范围外事项
1. 风险与缓解措施
10.5 投资与资源
1. 路线图与里程碑
11.5 市场进入策略
1. PDR 摘要

步骤 1.4：提交计划供批准

markdown

undefined

DAG Execution Plan

Feature-Areas detected: 3 Total sections: 15

Feature-Area: Core PDRs: PDR-001, PDR-005, PDR-008 DAG: Document Info → Executive Summary → Overview → Problem → Market Opportunity → Goals → Metrics → Personas → [Requirements Checkpoint] → NFRs → Out-of-Scope → Risks → Investment → Roadmap → GTM → PDR-Summary

Approve this plan? [Yes/Modify/Cancel]


**Step 1.5: Write state.json**

```json
{
  "version": "1.0",
  "phase": "plan_approved",
  "feature_areas": [
    {
      "id": "core",
      "name": "Core",
      "pdrs": ["PDR-001", "PDR-005"],
      "dag": ["document-info", "executive-summary", "overview", "problem", ...],
      "progress": {}
    }
  ],
  "checkpoint": {
    "enabled": true,
    "after_section": "requirements",
    "status": "pending"
  }
}

Feature-Areas detected: 3 Total sections: 15

Approve this plan? [Yes/Modify/Cancel]


**步骤 1.5：写入 state.json**

```json
{
  "version": "1.0",
  "phase": "plan_approved",
  "feature_areas": [
    {
      "id": "core",
      "name": "Core",
      "pdrs": ["PDR-001", "PDR-005"],
      "dag": ["document-info", "executive-summary", "overview", "problem", ...],
      "progress": {}
    }
  ],
  "checkpoint": {
    "enabled": true,
    "after_section": "requirements",
    "status": "pending"
  }
}

Phase 2: Execute

阶段 2：执行

For each section in the DAG:

Check dependencies — ensure all prerequisites completed
Load section template —
```
../templates/sections/{section}.md
```
Generate content — fill template with PDR-derived content

Write section file —

.adlc/product/sections/{feature-area}/{section}.md

Validate — run

scripts/bash/validate-prd.sh {section}.md

Update state.json — mark section as "completed"

Section template usage (MANDATORY):

Read template FIRST
Fill ALL [PLACEHOLDERS]
NEVER generate from scratch

In-section diagrams (MANDATORY):

Use
```
```mermaid
```
code blocks
Use
```
flowchart
```
keyword (NOT deprecated
```
graph
```
)
ASCII box-drawing characters are PROHIBITED
Diagrams embedded in their home sections

Section	Diagram Type	Subsection
2. Overview	Feature Hierarchy ( `flowchart TD` )	2.4
2. Overview	Architecture ( `flowchart TB` )	2.5
6. Personas	User Journey ( `journey` )	6.4
7. Requirements	Req Dependencies ( `flowchart LR` )	7.4
7. Requirements	Feature Dependencies ( `flowchart LR` )	7.5
11. Roadmap	Gantt Chart ( `gantt` )	11.1

Requirements Checkpoint (MANDATORY):

After generating Requirements section:

markdown

undefined

对于 DAG 中的每个章节：

检查依赖关系 — 确保所有前置项均已完成
加载章节模板 —
```
../templates/sections/{section}.md
```
生成内容 — 使用源自 PDR 的内容填充模板

写入章节文件 —

.adlc/product/sections/{feature-area}/{section}.md

验证 — 运行

scripts/bash/validate-prd.sh {section}.md

更新 state.json — 将章节标记为 "completed"

章节模板使用方式（强制）：

先读取模板
填写所有 [PLACEHOLDERS]
绝不从头生成

章节内图表（强制）：

使用
```
```mermaid
```
代码块
使用
```
flowchart
```
关键字（不要使用已弃用的
```
graph
```
）
禁止使用 ASCII 框线字符
图表嵌入其所属章节

章节	图表类型	子章节
2. 概述	功能层级（ `flowchart TD` ）	2.4
2. 概述	架构（ `flowchart TB` ）	2.5
6. 用户角色	用户旅程（ `journey` ）	6.4
7. 需求	需求依赖关系（ `flowchart LR` ）	7.4
7. 需求	功能依赖关系（ `flowchart LR` ）	7.5
11. 路线图	甘特图（ `gantt` ）	11.1

Requirements 检查点（强制）

生成 Requirements 章节后：

markdown

undefined

CHECKPOINT: Requirements Section Complete

The Requirements section has been generated.

Why checkpoint here? Requirements shapes:

NFRs (how requirements are met)
Out-of-Scope (what's NOT required)
Risks (technical feasibility)
Roadmap (priority and sequencing)

Options: A) Approve — Continue to remaining sections B) Modify — Edit requirements, then continue C) Restart — Regenerate from Problem phase D) Cancel — Stop execution

undefined

The Requirements section has been generated.

Why checkpoint here? Requirements shapes:

NFRs (how requirements are met)
Out-of-Scope (what's NOT required)
Risks (technical feasibility)
Roadmap (priority and sequencing)

Options: A) Approve — Continue to remaining sections B) Modify — Edit requirements, then continue C) Restart — Regenerate from Problem phase D) Cancel — Stop execution

undefined

Phase 3: Summarize

阶段 3：汇总

Step 3.1: Read All Sections FROM DISK

CRITICAL: Read each section file from filesystem. Do NOT use content from memory.

Scan
```
.adlc/product/sections/
```
for all
```
.md
```
files
Read each file
Validate: ≥20 lines, proper headers

Step 3.2: Detect Cross-Feature-Area Conflicts

Conflict Type	Detection	Resolution
Duplicate requirements	Same requirement, different wording	Standardize to PDR terminology
Priority mismatch	Same feature, different priority	Defer to PDR
Metric inconsistency	Same metric, different definition	Use PDR definition

Step 3.3: Aggregate into PRD.md

CRITICAL: PRD.md MUST be SELF-CONTAINED.
ALL diagrams embedded IN-SECTION
ZERO reader-facing links to
.adlc/
paths
Use in-document anchors only:
[Section 2.4](#24-feature-hierarchy)
PDR references as plain text:
plain-text PDR references
(NOT linked)

PRD structure (must match template):

markdown

undefined

步骤 3.1：从磁盘读取所有章节

关键：从文件系统读取每个章节文件。不要使用记忆中的内容。

扫描
```
.adlc/product/sections/
```
下的所有
```
.md
```
文件
读取每个文件
验证：≥20 行，标题正确

步骤 3.2：检测跨功能域冲突

冲突类型	检测方式	解决方式
重复需求	同一需求，不同表述	统一为 PDR 术语
优先级不一致	同一功能，不同优先级	以 PDR 为准
指标不一致	同一指标，不同定义	使用 PDR 定义

步骤 3.3：汇总至 PRD.md

关键：
PRD.md
必须自包含。
所有图表均嵌入对应章节
面向读者的
.adlc/
路径链接数量为零
仅使用文档内锚点：
[Section 2.4](#24-feature-hierarchy)
PDR 引用使用纯文本：
plain-text PDR references
（不要链接）

PRD 结构（必须与模板匹配）：

markdown

undefined

Product Requirements Document: [Product Name]

1. Document Information

[Quick Stats, revision history, approval]

1.5 Executive Summary

[Business case, ROI, recommendation]

2. Overview

[Product description, scope]

2.4 Feature Hierarchy [MERMAID flowchart TD]

2.5 Architecture Overview [MERMAID flowchart TB]

3. The Problem

[Problem statement, validation evidence]

3.5 Market Opportunity

[TAM/SAM/SOM, competitive landscape]

4. Goals & Objectives

[Primary, technical, business goals traced to PDRs]

5. Success Metrics

[Adoption, engagement, quality]

5.5 Business Outcome Metrics

5.6 Financial Metrics

6. Personas

[Primary, secondary, anti-personas]

6.4 User Journey [MERMAID journey]

7. Functional Requirements [CHECKPOINT]

[User stories, REQ-XXX IDs, priority matrix]

7.4 Requirement Dependencies [MERMAID flowchart LR]

7.5 Feature Dependencies [MERMAID flowchart LR]

8. Non-Functional Requirements

[Performance, security, reliability, scalability]

9. Out of Scope

[Feature, technical, market exclusions]

10. Risks & Mitigation

[Risk summary, technical, market, operational]

10.4 Business Risks

10.5 Investment & Resources

[Team, budget, ROI, go/no-go criteria]

11. Roadmap & Milestones

11.1 Roadmap Overview [MERMAID gantt]

[Milestone details with demo sentences]

11.2 Milestone Gates & Progress

[Per milestone: done-means definition, feature rollup, gate table, issue/evidence status — sourced from milestone PDRs]

11.5 Go-to-Market Strategy

[Launch phases, pricing, messaging]

12. PDR Summary

[Key decisions, constitution alignment — NO external links]

undefined

[Key decisions, constitution alignment — NO external links]

undefined

Phase 4: PDR Lifecycle Management (MANDATORY)

阶段 4：PDR 生命周期管理（强制）

Requires: the

product-clarify

skill (provides

pdr-lib.sh

adlc-cli skills add tikalk/adlc-team-skills --skill product-clarify

Step 4.1: Move Accepted PDRs to Memory (atomic — script-driven)

Source the PDR lifecycle library and call

move_pdr

for each Accepted PDR. This performs an atomic

mv

(no copy-then-delete duplication risk) and regenerates both scopes' indexes automatically.

bash

source "{REPO_ROOT}/.agents/skills/product-clarify/scripts/bash/pdr-lib.sh"

前置条件：

product-clarify

skill（提供

pdr-lib.sh

）：

adlc-cli skills add tikalk/adlc-team-skills --skill product-clarify

步骤 4.1：将已接受的 PDR 移至 Memory（原子操作，由脚本驱动）

加载 PDR 生命周期库，并为每个已接受的 PDR 调用

move_pdr

。此操作会执行原子

mv

（不存在先复制再删除所带来的重复风险），并自动重新生成两个作用域的索引。

bash

source "{REPO_ROOT}/.agents/skills/product-clarify/scripts/bash/pdr-lib.sh"

Or on Windows: . "{REPO_ROOT}/.agents/skills/product-clarify/scripts/powershell/pdr-lib.ps1"

for pdr_id in <list of Accepted PDR IDs>; do move_pdr "$pdr_id" drafts memory done


- PDRs with status "Accepted" are moved (not copied) from `.adlc/drafts/pdr/` to `docs/adlc/memory/pdr/`.
- **Do NOT change status to "Completed"** — keep status as "Accepted" so the index header ("Accepted PDRs only") remains truthful.
- Proposed/Discovered PDRs remain in drafts (not moved).
- Both `drafts/pdr/pdr.md` and `memory/pdr/pdr.md` indexes are regenerated by `move_pdr`.

**Step 4.2: Generate Memory PDR Index (MANDATORY — script-driven)**

The `move_pdr` call in Step 4.1 already regenerates the memory index. To manually regenerate (e.g., after bulk edits to PDR files):

```bash
source "{REPO_ROOT}/.agents/skills/product-clarify/scripts/bash/pdr-lib.sh"
generate_pdr_index memory

This writes

{REPO_ROOT}/docs/adlc/memory/pdr/pdr.md

using a frontmatter-primary + heading-fallback parser that handles both

##

(H2 legacy) and

###

(H3 current) metadata. Blank cells trigger a stderr warning and defaults are applied — no silent blank rows.

The generated index has this format:

markdown

undefined

for pdr_id in <list of Accepted PDR IDs>; do move_pdr "$pdr_id" drafts memory done


- status 为 "Accepted" 的 PDR 会从 `.adlc/drafts/pdr/` **移动**（而非复制）至 `docs/adlc/memory/pdr/`。
- **不要将 status 改为 "Completed"** — 保持 status 为 "Accepted"，确保索引标题（"Accepted PDRs only"）仍然准确。
- Proposed/Discovered PDR 保留在 drafts 中（不移动）。
- `move_pdr` 会重新生成 `drafts/pdr/pdr.md` 和 `memory/pdr/pdr.md` 两个索引。

**步骤 4.2：生成 Memory PDR 索引（强制，由脚本驱动）**

步骤 4.1 中的 `move_pdr` 调用已经重新生成 memory 索引。如需手动重新生成（例如批量编辑 PDR 文件后），可执行：

```bash
source "{REPO_ROOT}/.agents/skills/product-clarify/scripts/bash/pdr-lib.sh"
generate_pdr_index memory

这会使用以 frontmatter 为主、以标题为回退的解析器，将

{REPO_ROOT}/docs/adlc/memory/pdr/pdr.md

写入对应位置；该解析器可同时处理

##

（旧版 H2）和

###

（当前 H3）元数据。空单元格会触发 stderr 警告并应用默认值——不会静默留下空白行。

生成的索引采用以下格式：

markdown

undefined

Product Decision Records (Memory)

Auto-generated by /product-implement. Accepted PDRs only. Source: docs/adlc/memory/pdr/PDR-*.md

PDR Index

ID	Feature-Area	Category	Status	Date	Owner	Title
PDR-001	control-plane	Governance	Accepted	2026-08-04	User/AI collaboration	Lit Factory Operating Model


This index is consumed by `team-boot` for session-start injection (similar to how `CDR.md` is used for team-level context).

**Step 4.3: Update state.json**

```json
{
  "phase": "completed",
  "pdr_lifecycle": {
    "pdrs_promoted": [N],
    "memory_pdr_moved": true,
    "drafts_retained": true,
    "drafts_reason": "Proposed/Discovered PDRs remain",
    "memory_index_generated": true
  }
}

ID	Feature-Area	Category	Status	Date	Owner	Title
PDR-001	control-plane	Governance	Accepted	2026-08-04	User/AI collaboration	Lit Factory Operating Model


该索引供 `team-boot` 在会话启动时注入使用（类似于团队级上下文使用 `CDR.md` 的方式）。

**步骤 4.3：更新 state.json**

```json
{
  "phase": "completed",
  "pdr_lifecycle": {
    "pdrs_promoted": [N],
    "memory_pdr_moved": true,
    "drafts_retained": true,
    "drafts_reason": "Proposed/Discovered PDRs remain",
    "memory_index_generated": true
  }
}

Phase 5: Final Verification

阶段 5：最终验证

Before marking complete, verify ALL checks:

#	Check	Expected
1	Section files on disk	N files in `.adlc/product/sections/`
2	PRD.md exists	Yes
3	PRD.md content size	>200 lines
4	PRD.md has all sections	Sections 1-12 + sub-sections
5	PRD.md is self-contained	0 `.adlc/` links
6	Diagrams embedded	≥4 `mermaid` blocks
7	Memory PDRs written	`docs/adlc/memory/pdr/PDR-*.md` exist
8	Memory PDR index generated	`docs/adlc/memory/pdr/pdr.md` exists with correct table
9	state.json consistent	All sections "completed"

Gate Rule: If ANY check fails → do NOT mark as completed. Report failures.

在标记完成之前，验证所有检查项：


.adlc/product/sections/
PRD.md
PRD.md
PRD.md
.adlc/
mermaid
docs/adlc/memory/pdr/PDR-*.md
docs/adlc/memory/pdr/pdr.md
state.json

#	检查项	预期结果
1	磁盘上的章节文件	`.adlc/product/sections/` 中有 N 个文件
2	`PRD.md` 存在	是
3	`PRD.md` 内容大小	>200 行
4	`PRD.md` 包含所有章节	第 1-12 节及子章节
5	`PRD.md` 自包含	0 个 `.adlc/` 链接
6	图表已嵌入	≥4 个 `mermaid` 代码块
7	Memory PDR 已写入	`docs/adlc/memory/pdr/PDR-*.md` 存在
8	Memory PDR 索引已生成	`docs/adlc/memory/pdr/pdr.md` 存在且表格正确
9	`state.json` 一致	所有章节均为 "completed"

门禁规则：如果任何检查失败 → 不得标记为已完成。报告失败项。

Claiming Ledger Slots (do this before writing any numbered id)

编号认领槽位（写入任何带编号的 ID 前执行）

A number computed from a stale base is wrong even when you compute it correctly — the working tree simply does not know what the merge target has already used. Check first, then read each number from the document; never eyeball it.

bash

undefined

即使计算方式正确，基于过期基线计算出的编号仍是错误的，因为工作树并不知道合并目标已经使用了哪些编号。必须先检查，再从文档中读取每个编号；绝不能凭肉眼判断。

bash

undefined

1. Refuse to proceed on a stale base (returns 1 and explains).

source {REPO_ROOT}/.agents/skills/product-clarify/scripts/bash/pdr-lib.sh require_current_base "${MERGE_TARGET:-origin/main}"

2. Read the next free number for each slot type.

next_record_number PDR "{REPO_ROOT}/.adlc/drafts/pdr" "{REPO_ROOT}/docs/adlc/memory/pdr" # record id -> 138 (drafts + published) next_prd_section "{PRD_FILE}" #

## 26.

heading -> 27 next_req_id "{PRD_FILE}" #

REQ-216

-> 217 next_feature_number "{PRD_FILE}" #

| 69 |

row -> 70


Each scan is deliberately over-inclusive: a match anywhere in the document
raises the result. That is the safe direction — an unused number is harmless,
a reissued one collides. `next_ad_delta_version` in `setup-architect.sh` is the
AD.md counterpart and belongs to `architect-implement`.

next_record_number PDR "{REPO_ROOT}/.adlc/drafts/pdr" "{REPO_ROOT}/docs/adlc/memory/pdr" # record id -> 138 (drafts + published) next_prd_section "{PRD_FILE}" #

## 26.

heading -> 27 next_req_id "{PRD_FILE}" #

REQ-216

-> 217 next_feature_number "{PRD_FILE}" #

| 69 |

row -> 70


每次扫描都刻意采用过度包容策略：文档中任何位置出现匹配项都会提高结果。这更安全——未使用的编号无害，而重复签发编号会发生冲突。`next_ad_delta_version` 是 `setup-architect.sh` 中对应的 `AD.md` 编号机制，属于 `architect-implement`。

PDR Traceability Rules

PDR 可追溯性规则

Every section must reference source PDRs with ID
Every requirement (REQ-XXX) must trace to a PDR
No content without PDR backing
PDRs are source of truth for conflict resolution

每个章节都必须通过 ID 引用源 PDR
每项需求（REQ-XXX）都必须追溯到 PDR
任何内容都不得缺少 PDR 依据
解决冲突时，PDR 是事实来源

Configuration

配置

PDR_DRAFTS_DIR

—

{REPO_ROOT}/.adlc/drafts/pdr

PDR_MEMORY_DIR

—

{REPO_ROOT}/docs/adlc/memory/pdr

PRD_FILE

—

{REPO_ROOT}/docs/adlc/product/PRD.md

SECTIONS_DIR

—

{REPO_ROOT}/.adlc/product/sections

STATE_FILE

—

{REPO_ROOT}/.adlc/product/state.json

```
PDR_DRAFTS_DIR
```
— PDR 草稿目录
```
PDR_MEMORY_DIR
```
— PDR Memory 目录
```
PRD_FILE
```
— PRD 文件路径
```
SECTIONS_DIR
```
— 章节目录
```
STATE_FILE
```
— 状态文件

12-Factor Alignment

12-Factor 对齐

Factor III (Mission Definition): Compiles mission decisions into actionable requirements
Factor IV (Structured Planning): DAG orchestration separates planning from execution
Factor IX (Traceability): Every PRD element traces back to a PDR

Factor III（使命定义）：将使命决策编译为可执行需求
Factor IV（结构化规划）：DAG 编排将规划与执行分离
Factor IX（可追溯性）：每个 PRD 元素都可追溯到 PDR

Common Rationalizations

常见借口

Rationalization	Reality
"I'll skip the checkpoint and just generate everything."	Requirements shapes NFRs, Out-of-Scope, Risks, and Roadmap. Skipping the checkpoint risks cascading errors.
"The PRD can reference section files."	PRD.md MUST be self-contained. External references break when section files are moved or deleted.
"I don't need to move PDRs to memory."	Without promotion, drafts and memory diverge. The next clarify session sees stale data.

借口	实际情况
“我会跳过检查点，直接生成全部内容。”	需求会影响非功能需求、范围外事项、风险和路线图。跳过检查点可能导致错误级联。
“PRD 可以引用章节文件。”	`PRD.md` 必须自包含。外部引用会在章节文件被移动或删除后失效。
“不需要把 PDR 移到 memory。”	如果不执行迁移，草稿和 memory 会发生分歧。下一次 `/product-clarify` 会话将看到过期数据。

Red Flags

危险信号

Generating PRD from non-Accepted PDRs — implement skips Proposed/Discovered; the PRD will be incomplete.
Writing PRD.md directly from PDRs — content MUST come from section files to ensure validation passed.
Missing the Requirements checkpoint — this is the cornerstone section; errors here cascade.
Leaving
.adlc/
links in PRD.md — breaks self-containment; readers cannot follow internal paths.

使用未接受的 PDR 生成 PRD — implement 会跳过 Proposed/Discovered；这样生成的 PRD 将不完整。
直接从 PDR 编写
PRD.md
— 内容必须来自章节文件，以确保验证已通过。
缺少 Requirements 检查点 — 这是核心章节；此处错误会级联。
在
PRD.md
中保留
.adlc/
链接 — 会破坏自包含性；读者无法访问内部路径。

Verification

验证

Pre-flight: ≥1 Accepted PDR exists
Plan approved by user
state.json written with DAG
Each section file ≥20 lines
validate-prd.sh passes for each section
Requirements checkpoint approved by user
PRD.md >200 lines with all 15 sections
Zero
```
.adlc/
```
links in PRD.md
≥4 Mermaid diagrams embedded in-section
All requirements trace to PDRs
Accepted PDRs moved to
```
docs/adlc/memory/pdr/
```
Final completion verification: all 8 checks pass

预检：至少存在 1 个已接受的 PDR
用户已批准计划
已写入包含 DAG 的
```
state.json
```
每个章节文件均 ≥20 行
每个章节的
```
validate-prd.sh
```
均通过
用户已批准 Requirements 检查点
```
PRD.md
```
>200 行，且包含全部 15 个章节
```
PRD.md
```
中有 0 个
```
.adlc/
```
链接
所在章节中嵌入了 ≥4 个 Mermaid 图表
所有需求均可追溯到 PDR
已接受的 PDR 已移至
```
docs/adlc/memory/pdr/
```
最终完成验证：全部 8 项检查通过