product-implement

Scope rule: scripts stay skill-local — never source a script from another skill. For another skill's operations, invoke that skill (e.g. architect-clarify, product-clarify, team-boot) via the Skill tool; for its documents, follow the Requires line. scripts/ and references/ below are relative to this skill. {REPO_ROOT} denotes the project root (where .adlc/ lives).

What this skill does

Transforms accepted PDRs into a comprehensive, self-contained PRD.md using a three-phase DAG:

1. Plan Agent: Analyze PDRs, detect feature-areas, generate customized DAG, get user approval
2. Execute Agent: Generate sections per feature-area with mandatory checkpoint after Requirements
3. 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)

When to use

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

When NOT to use

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

Pre-Flight Validation

Before starting, verify prerequisites:

1. Check PDRs exist: {REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md
2. 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

Three-Phase DAG Workflow

┌─────────────────────────────────────────────────────────┐
│ 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

Step 1.1: Load and Analyze PDRs

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

Step 1.2: Detect Feature-Area Characteristics

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
• 2. Overview
• 3. The Problem
• 3.5 Market Opportunity
• 4. Goals & Objectives
• 5. Success Metrics
• 6. Personas
• 7. Functional Requirements
• 8. Non-Functional Requirements
• 9. Out of Scope
• 10. Risks & Mitigation
• 10.5 Investment & Resources
• 11. Roadmap & Milestones
• 11.5 Go-to-Market Strategy
• 12. PDR Summary

Step 1.4: Present Plan for Approval

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

{
  "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

For each section in the DAG:

1. Check dependencies — ensure all prerequisites completed
2. Load section template — the canonical template skills/product/templates/sections/{section}.md in the adlc-team-skills checkout. Templates ship only with the owning skill — the installed product-clarify skill has no templates/ directory, so a relative ../../product-clarify/templates/ path resolves nowhere; do not use it. If the file is absent in your installed layout, generate the section from the PRD structure outline in Step 3.3 instead.
3. Generate content — fill template with PDR-derived content
4. Write section file — .adlc/product/sections/{feature-area}/{section}.md
5. Validate — run scripts/bash/validate-prd.sh {section}.md
6. 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

Requirements Checkpoint (MANDATORY):

After generating Requirements section:

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

Phase 3: Summarize

Step 3.1: Read All Sections FROM DISK

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

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

Step 3.2: Detect Cross-Feature-Area Conflicts

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

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

Phase 4: PDR Lifecycle Management (MANDATORY)

Requires: the product-clarify skill for PDR lifecycle operations (index generation, promotion, clarification): adlc-cli skills add tikalk/adlc-team-skills --skill product-clarify

Step 4.1: Move Accepted PDRs to Memory (atomic — owned by product-clarify)

Invoke the product-clarify skill for the promotion; its move_pdr operation moves each Accepted PDR with an atomic mv (no copy-then-delete duplication risk) and regenerates both scopes' indexes automatically. Pass the Accepted PDR IDs (<list of Accepted PDR IDs>) with scope drafts memory.

• 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 promotion in Step 4.1 already regenerates the memory index. To manually regenerate (e.g., after bulk edits to PDR files), invoke the product-clarify skill and run its generate_pdr_index memory operation.

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:

# 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

{
  "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

Before marking complete, verify ALL checks:

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

Claiming Ledger Slots (do this before writing any numbered 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 the base first, then read each number from the setup output; never eyeball it.

# 1. Refuse to proceed on a stale base.
git fetch origin --quiet
test "$(git rev-list --count "HEAD..${MERGE_TARGET:-origin/main}")" = 0 \
  || { echo "base is behind ${MERGE_TARGET:-origin/main}; rebase before claiming a slot" >&2; exit 1; }

# 2. Read the next free slot for each type from the setup JSON.
bash scripts/bash/setup-product-implement.sh --json

The setup script vendors these scans (scripts stay skill-local), so the numbers come from the checkout rather than from a helper that may not be installed. 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.

PDR Traceability Rules

• 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

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

12-Factor Alignment

• 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

Common Rationalizations

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.

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