product-specify

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 a high-level product idea into documented Product Decision Records (PDRs) through interactive exploration and trade-off analysis.

Key insight: Discussion and exploration happen before committing to formal documentation. The goal is to surface trade-offs, validate assumptions, and make informed decisions collaboratively.

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

When to use

Note: Class boots detect decisions and suggest this skill — running it is how the capture happens (it writes the lightweight draft to .adlc/drafts/). Use it for interactive deep-dive exploration — when you want guided trade-off analysis, multi-option comparison, or structured decision facilitation before documenting.

• New product from scratch
• Major product pivots
• Documenting verbal decisions formally
• Team onboarding — walking through product rationale

When NOT to use

• Existing product (use /product-init instead)
• Minor PDR updates (use /product-clarify instead)

Execution Steps

Phase 0: Environment Setup

sh: scripts/bash/setup-product-specify.sh [--json]
ps: scripts/powershell/setup-product-specify.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",
  "next_pdr": "001"
}

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

Phase 1: Feature-Area Decomposition (Optional)

Analyze the product for distinct business domains. Auto-decompose if multiple domains detected. Use --no-decompose to skip.

Present detected areas:

## Detected Feature Areas

| # | Feature Area | Key Domains | Rationale |
|---|--------------|-------------|-----------|
| 1 | **Auth** | Authentication, Authorization | Core user entry |
| 2 | **Core** | User Management, Profiles | Core data |
| 3 | **Business** | Payments, Subscriptions | Revenue domain |

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

Threshold:

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

• 6 areas: Suggest grouping

Phase 2: Product Analysis

Extract product drivers:

1. Problem Drivers: Core problem, who experiences it, current workarounds
2. Market Drivers: Target segments, competitive landscape, trends
3. Business Drivers: Revenue model, scaling expectations, strategic importance
4. Constraint Drivers: Technology mandates, budget, team skills, regulatory
5. Load Constitution: Read {REPO_ROOT}/docs/adlc/memory/constitution.md (legacy {REPO_ROOT}/.adlc/memory/constitution.md fallback — dual-read) if either exists
6. Check Existing Docs: Scan README.md, AGENTS.md, CONTRIBUTING.md for context

Phase 3: Product Exploration (Interactive)

For each major decision area, present options and facilitate discussion:

Decision areas (5-7 key decisions):

1. Problem Scope
2. Target Personas
3. Solution Approach (build vs buy vs partner)
4. Monetization
5. Go-to-Market
6. Success Metrics

Exploration format:

## Product Decision: [Decision Area]

**Context**: [Why this decision matters]

**Options**:
| Option | Description | Trade-offs |
|--------|-------------|------------|
| A | [Option A] | Pros: [X] / Cons: [Y] |
| B | [Option B] | Pros: [X] / Cons: [Y] |

**Recommended**: Option [X]

**Questions**:
1. [Question about constraints]
2. [Question about trade-off priorities]

Rules:

• Present one decision area at a time
• Always provide a recommended option with reasoning
• Ask targeted questions to surface hidden requirements
• Skip decisions already determined by context or constitution
• Limit to 5-7 key decisions

Phase 4: Cross-Feature-Area Pre-Analysis

During exploration, watch for:

Phase 5: Decision Documentation

After each decision is confirmed, create a PDR file.

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 (Context, Decision, Consequences, Alternatives, Links).

---
status: proposed
date: YYYY-MM-DD
owner: [User/AI collaboration]
category: Feature
feature-area: [core | business | growth | ...]
title: [Decision Title]
---

# PDR-[NNN]: [Decision Title]

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

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

## Decision
**Decision Statement:**
[Clear statement of what was decided]

**Rationale:**
[Why this option was chosen]

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

### Constitution/Vision Alignment
| Principle | Alignment | Notes |
|-----------|-----------|-------|
| [Vision Principle] | ✅ Compliant / ⚠️ Deviation | [Explanation] |

Phase 6: Write PDR Files and Regenerate Index

1. Number PDRs sequentially: Start from PDR-001 for new projects, or continue from the next free slot the setup script computes (next_pdr in its JSON/status output) — never from "the highest existing PDR number" guessed by inspection: a stemmed record (e.g. PDR-002-amendment-2.md) is easy to miss, and its slot is still taken
2. Write individual files: {REPO_ROOT}/.adlc/drafts/pdr/PDR-{NNN}.md
3. Regenerate index: {REPO_ROOT}/.adlc/drafts/pdr/pdr.md

Index format:

# Product Decision Records

## PDR Index

| ID | Feature-Area | Category | Status | Date | Owner |
|----|--------------|----------|--------|------|-------|
| PDR-001 | System | Target Market | Proposed | 2026-03-09 | User/AI |
| PDR-002 | Auth | Primary Persona | Proposed | 2026-03-09 | User/AI |

---

*Individual PDR files: PDR-*.md in this directory*

Phase 7: Summary Report

## Feature Area Decomposition Summary

### Feature Areas Identified: 3

| # | Feature Area | PDRs Created |
|---|--------------|--------------|
| 1 | System-Level | PDR-001: Target Market |
| 2 | Auth | PDR-002: Primary Persona, PDR-003: Authentication Approach |
| 3 | Business | PDR-004: Pricing Model, PDR-005: Payment Integration |

### Next Steps
1. Review PDRs with /product-clarify
2. Generate PRD.md with /product-implement

PDR Numbering Rules

• Number from the next free slot the setup script computes (next_pdr), 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 scan reads every PDR-* stem in {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
• Never reuse numbers

Key Rules

Exploration First

• Do NOT generate PRD directly from product description
• Engage in discussion to validate assumptions
• Surface trade-offs before committing to decisions
• Allow iteration — user can revisit earlier decisions

Constitution Compliance

• PDRs must align with constitution principles
• Flag conflicts between product requirements and constitution
• Constitution violations require explicit override with justification

Incremental PDRs

• Create focused PDRs — one decision per PDR
• Link related PDRs when decisions interact
• Defer decisions that can be made later
• Mark provisional decisions that may need revision

Configuration

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PDR_INDEX — {REPO_ROOT}/.adlc/drafts/pdr/pdr.md
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md
• CONSTITUTION — {REPO_ROOT}/docs/adlc/memory/constitution.md (legacy .adlc/memory/constitution.md fallback)

12-Factor Alignment

• Factor III (Mission Definition): Defines the product mission before execution
• Factor XI (Directives as Code): PDRs are version-controlled decision records

Common Rationalizations

Red Flags

• Generating PRD before PDRs are accepted — /product-implement requires Accepted status; Proposed PDRs will be skipped.
• Skipping the constitution check — misaligned decisions propagate into the PRD and become expensive to fix.
• No alternatives documented — a PDR without alternatives is a statement, not a decision.

Verification

• Setup script returns valid JSON with all paths
• .adlc/drafts/pdr/ directory exists
• At least one PDR-*.md file created with status "Proposed"
• pdr.md index auto-generated with correct table
• Constitution alignment checked (if constitution exists)
• Cross-feature-area conflicts flagged
• No duplicate PDR IDs
• Each PDR has at least 2 alternatives documented