product-init

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

Reverse-engineers product decisions from an existing product using a three-phase analysis pipeline:

1. Discovery Agent: Scans each feature-area for raw product signals (code, docs, pricing)
2. Pattern Agent: Classifies signals into PDR categories, scores strategic importance
3. Synthesis Agent: Cross-feature-area analysis, flags inconsistencies

Output: Individual PDR-{NNN}.md files (status Discovered) in .adlc/drafts/pdr/ with an auto-generated pdr.md index.

When to use

• Existing product with no formal PDRs
• Brownfield codebase needs product documentation
• Team onboarding — walking through product rationale
• Post-acquisition or inherited codebase

When NOT to use

• New product (use /product-specify instead)
• Minor PDR updates (use /product-clarify instead)

Execution Steps

Phase 0: Environment Setup

Run setup script to resolve paths and detect feature-areas:

sh: scripts/bash/setup-product-init.sh [--json]
ps: scripts/powershell/setup-product-init.ps1

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

Setup output (JSON):

{
  "REPO_ROOT": "/path/to/project",
  "PDR_DRAFTS_DIR": "/path/to/project/.adlc/drafts/pdr",
  "PRD_FILE": "/path/to/project/PRD.md",
  "feature_areas": ["core", "business", "growth"],
  "next_pdr": "001"
}

The script reports next_pdr — the next free PDR slot (status line Next PDR: PDR-{NNN}); Phase 5 numbers the new PDRs from it

Create directories:

mkdir -p "{REPO_ROOT}/.adlc/drafts/pdr"
mkdir -p "{REPO_ROOT}/.adlc/product"

Phase 1: Feature-Area Detection

Detect feature-areas from three sources:

Present detected areas:

## Detected Feature-Areas

| # | Feature-Area | Sources | Evidence |
|---|--------------|---------|----------|
| 1 | **Core** | Directory + Docs | src/users/, README "Core Features" |
| 2 | **Business** | Directory + Pricing | src/billing/, pricing.md tiers |

Reply: Y to confirm, n for monolithic, or suggest changes.

Threshold Logic:

• ≤3 areas: Auto-approve
• 4-6 areas: Confirm with user

• 6 areas: Suggest grouping

Phase 2: Discovery Agent (Per Feature-Area)

For each feature-area in order:

1. Scan directory for monetization signals, user flows, features
2. Analyze documentation (README, PRD, pricing)
3. Identify pricing tier mappings
4. Document evidence

Progress report per area:

Discovery Agent: business feature-area
├── Directory signals: 4
├── Documentation signals: 2
├── Pricing signals: 1
└── Status: ✓ Completed

Phase 3: Pattern Agent (Per Feature-Area)

For each feature-area:

1. Categorize signals into PDR categories (Problem, Persona, Scope, Metric, etc.)
2. Score strategic importance (0.0-1.0)
3. Check for duplicates against existing PDRs
4. Identify cross-area candidates

Phase 4: Synthesis Agent (Cross-Feature-Area)

1. Cross-Area Pattern Detection:

{
  "pattern_id": "P001",
  "pattern_name": "Admin Persona",
  "feature_area_presence": {"core": true, "business": true},
  "is_cross_area": true
}

2. Inconsistency Detection:

• Priority conflicts
• Duplicate problems
• Inconsistent metrics
• Generate flags (embedded in affected PDRs)

3. PDR Generation: High-strategic patterns (>0.7) and cross-area patterns (≥2 areas)

Phase 5: Write Individual PDR Files

For each discovered PDR:

1. Assign ID: PDR-{NNN} using next available number
2. Write file: {REPO_ROOT}/.adlc/drafts/pdr/PDR-{NNN}.md

PDR file format (individual file, YAML frontmatter — use the shared template):

Use the canonical template skills/product/templates/pdr-template.md in the adlc-team-skills checkout as the canonical PDR format (family-level templates are checkout-only — they do not ship with an installed skill). If the template file is absent in your checkout, use the inline PDR format below instead. The template includes YAML frontmatter (status, date, owner, category, feature-area, title) as the single source of truth for index generation, plus the standard PDR body sections.

---
status: discovered
date: YYYY-MM-DD
owner: [Inferred from codebase/authors]
category: [Problem | Persona | Scope | Metric | Prioritization | Business Model | Feature | NFR]
feature-area: [core | business | growth | ...]
title: [Decision Title]
---

# PDR-001: [Decision Title]

### Cross-Feature-Area Metadata
- **Appears in**: [business, growth]
- **Cross-area count**: 2
- **Is cross-area pattern**: ✓

### ⚠️ Inconsistency Flags
*None* (or flag details if detected)

### Context
**Problem/Opportunity:**
[Clear description]

**Market Forces:**
- [Market factor 1]
- [Customer feedback]

### Decision
**Decision Statement:**
[Clear statement]

**Rationale:**
[Why this option]

### Consequences
#### Positive
- [Benefit 1]

#### Negative
- [Trade-off 1]

#### Risks
- [Risk with mitigation]

### Success Metrics
| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| [Metric] | [Target] | [Method] |

### Alternatives Considered
#### Option A: [Alternative Name]
**Description:** [Brief description]
**Trade-offs:** [Neutral comparison]

Phase 6: Regenerate PDR Index

Generate {REPO_ROOT}/.adlc/drafts/pdr/pdr.md from all PDR-*.md files:

# For each PDR-*.md file, extract ID, title, status, date
# Build index table

Index format:

# Product Decision Records

## PDR Index

| ID | Feature-Area | Category | Status | Date | Owner |
|----|--------------|----------|--------|------|-------|
| PDR-001 | business | Business Model | Discovered | 2026-01-20 | [Inferred] |
| PDR-002 | core | Persona | Discovered | 2026-01-20 | [Inferred] |

---

## Cross-Feature-Area Analysis Summary

### Cross-Area Patterns
| Pattern | Feature-Areas | PDR |
|---------|---------------|-----|
| Admin Persona | core, business | PDR-002 |

### Inconsistencies Flagged
| Flag ID | Type | PDRs Affected | Severity |
|---------|------|---------------|----------|
| FLG-001 | Priority Conflict | PDR-003 | Medium |

---

*Individual PDR files are in this directory (PDR-*.md)*

Phase 7: Output Summary

## Product Init Complete ✓

### Execution Stats
- **Feature-areas analyzed**: 3
- **Discovery Agent runs**: 3
- **Pattern Agent runs**: 3
- **Synthesis Agent runs**: 1

### PDRs Generated
| Category | Count | Cross-Area |
|----------|-------|------------|
| Business Model | 2 | ✓ |
| Persona | 3 | ✓ |
| Problem | 2 | |
| Prioritization | 1 | |
| **With Inconsistency Flags** | **2** | |

### Next Steps
1. Review PDRs: `{REPO_ROOT}/.adlc/drafts/pdr/`
2. **Resolve inconsistencies**: Run `/product-clarify`
3. Generate PRD: Run `/product-implement`

PDR Numbering Rules

• Number from the next free slot the setup script computes and emits (next_pdr in its JSON/status output), never from "the highest existing number" guessed by inspection: a stemmed record (e.g. PDR-002-amendment-2.md) is easy to miss, and its slot is still taken
• The slot rule: a record's number is the leading digits of its filename stem; the maximum spans {REPO_ROOT}/.adlc/drafts/pdr/ and published memory (docs/adlc/memory/pdr/) — the same source next_pdr reports
• PDR IDs are zero-padded to 3 digits (PDR-001, PDR-002, ...)
• Never reuse numbers, even for deleted PDRs

State Management

State file: {REPO_ROOT}/.adlc/product/state.json

{
  "version": "1.0",
  "command": "product-init",
  "created_at": "2026-01-20T10:00:00Z",
  "phase": "completed",
  "feature_areas": [
    {"id": "core", "name": "Core", "progress": {"discovery": "completed", "pattern": "completed"}}
  ],
  "pdrs_generated": 9,
  "cross_area_patterns": 5,
  "inconsistencies": 2
}

Configuration

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr (individual PDR files)
• PDR_INDEX — {REPO_ROOT}/.adlc/drafts/pdr/pdr.md (auto-generated index)
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md
• STATE_FILE — {REPO_ROOT}/.adlc/product/state.json

12-Factor Alignment

• Factor III (Mission Definition): Discovers the "what & why" behind existing code
• Factor IX (Traceability): Every inferred decision is documented with evidence

Common Rationalizations

Red Flags

• Generating PDRs without codebase evidence — brownfield PDRs must be grounded in actual code/docs, not fabricated rationales.
• Skipping inconsistency flags — cross-area conflicts are real signals, not noise.
• Assigning "Proposed" status to discovered PDRs — brownfield PDRs are Discovered, not proposed.

Verification

• Setup script returns valid JSON with all paths
• .adlc/drafts/pdr/ directory exists
• At least one PDR-*.md file created with status "Discovered"
• pdr.md index auto-generated with correct table
• State file written to .adlc/product/state.json
• Inconsistency flags embedded in affected PDRs (not separate files)
• Cross-feature-area analysis summary in index
• No duplicate PDR IDs