Product Specify

product-specify

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: Routine decision capture is handled by team-boot's continuous capture mechanism, which writes lightweight drafts directly to .adlc/drafts/. This skill is 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 (provides pdr-lib.sh): 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"
}

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 — ADR-401 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 template at {REPO_ROOT}/.agents/skills/product/templates/pdr-template.md as the canonical PDR format. 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] |