scripts/bash/setup-product-specify.sh
#!/bin/bash
# product-specify setup script
set -euo pipefail
JSON_MODE=false
for arg in "$@"; do
case "$arg" in --json) JSON_MODE=true ;; esac
done
_get_project_root() {
local dir
dir="$(pwd)"
while [ "$dir" != "/" ]; do
if [ -d "$dir/.adlc" ] || [ -d "$dir/.git" ]; then
echo "$dir"
return 0
fi
dir="$(dirname "$dir")"
done
pwd
}
# JSON output is built with jq -n -c (jq is required; no fallbacks).
# Layout roots (.adlc/ machine pipeline; docs/adlc/ human-facing deliverables)
ADLC_DIR="${ADLC_DIR:-.adlc}"
DOCS_ADLC_DIR="${DOCS_ADLC_DIR:-docs/adlc}"
DOCS_ADLC_MEMORY="${DOCS_ADLC_MEMORY:-docs/adlc/memory}"
DOCS_ADLC_PRODUCT="${DOCS_ADLC_PRODUCT:-docs/adlc/product}"
DOCS_ADLC_ARCHITECT="${DOCS_ADLC_ARCHITECT:-docs/adlc/architect}"
ADLC_DRAFTS="${ADLC_DRAFTS:-.adlc/drafts}"
# Ledger slot allocation (vendored from product-clarify pdr-lib.sh):
# leading digits of the filename stem, max across drafts AND published memory.
next_record_number() {
local prefix="$1"
shift
local max=0 f num
local dir
for dir in "$@"; do
[ -d "$dir" ] || continue
for f in "$dir"/"${prefix}"-*.md; do
[ -f "$f" ] || continue
num=$(basename "$f" .md | sed -n "s/^${prefix}-\([0-9]\{1,\}\).*/\1/p")
[ -n "$num" ] || continue
((10#$num > max)) && max=$((10#$num))
done
done
printf '%03d' "$((max + 1))"
}
REPO_ROOT="${REPO_ROOT:-$(_get_project_root)}"
PDR_DRAFTS_DIR="$REPO_ROOT/${ADLC_DRAFTS:-.adlc/drafts}/pdr"
PRD_FILE="$REPO_ROOT/${DOCS_ADLC_PRODUCT:-docs/adlc/product}/PRD.md"
mkdir -p "$PDR_DRAFTS_DIR"
# Ledger slot allocation (vendored): leading
# digits of the filename stem, max across drafts AND published memory. This
# script previously carried its own copy, which silently skipped stemmed
# records (PDR-002-amendment-2.md) and scanned drafts alone.
NEXT_PDR=$(next_record_number PDR "$PDR_DRAFTS_DIR" \
"$REPO_ROOT/${DOCS_ADLC_MEMORY:-docs/adlc/memory}/pdr")
PDR_COUNT=$(find "$PDR_DRAFTS_DIR" -name 'PDR-*.md' 2>/dev/null | wc -l)
if $JSON_MODE; then
jq -n -c --arg rr "$REPO_ROOT" --arg pdd "$PDR_DRAFTS_DIR" --arg pf "$PRD_FILE" \
--arg np "$NEXT_PDR" --argjson n "$PDR_COUNT" \
'{REPO_ROOT:$rr,PDR_DRAFTS_DIR:$pdd,PRD_FILE:$pf,next_pdr:$np,pdr_count:$n}'
else
echo "[INFO] product-specify setup"
echo " REPO_ROOT: $REPO_ROOT"
echo " PDR_DRAFTS_DIR: $PDR_DRAFTS_DIR"
echo " Next PDR: PDR-$NEXT_PDR"
echo " Existing PDRs: $PDR_COUNT"
fi
scripts/powershell/setup-product-specify.ps1
# product-specify setup script (PowerShell)
param([switch]$Json)
$ErrorActionPreference = "Stop"
# Layout roots (.adlc/ machine pipeline; docs/adlc/ human-facing deliverables)
$ADLC_DIR = if ($env:ADLC_DIR) { $env:ADLC_DIR } else { ".adlc" }
$DOCS_ADLC_DIR = if ($env:DOCS_ADLC_DIR) { $env:DOCS_ADLC_DIR } else { "docs/adlc" }
$DOCS_ADLC_MEMORY = if ($env:DOCS_ADLC_MEMORY) { $env:DOCS_ADLC_MEMORY } else { "docs/adlc/memory" }
$DOCS_ADLC_PRODUCT = if ($env:DOCS_ADLC_PRODUCT) { $env:DOCS_ADLC_PRODUCT } else { "docs/adlc/product" }
$DOCS_ADLC_ARCHITECT = if ($env:DOCS_ADLC_ARCHITECT) { $env:DOCS_ADLC_ARCHITECT } else { "docs/adlc/architect" }
$ADLC_DRAFTS = if ($env:ADLC_DRAFTS) { $env:ADLC_DRAFTS } else { ".adlc/drafts" }
$RepoRoot = $(git rev-parse --show-toplevel 2>$null); if (-not $RepoRoot) { $RepoRoot = Get-Location }
$PdrDraftsDir = Join-Path $RepoRoot ".adlc/drafts/pdr"
$PrdFile = Join-Path $RepoRoot "docs/adlc/product/PRD.md"
New-Item -ItemType Directory -Force -Path $PdrDraftsDir | Out-Null
# Ledger slot allocation (vendored from product-clarify pdr-lib.ps1):
# leading digits of the filename stem, max across drafts AND published memory.
function Get-NextRecordNumber {
param(
[Parameter(Mandatory = $true)][string]$Prefix,
[Parameter(Mandatory = $true)][string[]]$Dirs
)
$max = 0
foreach ($dir in $Dirs) {
if (-not (Test-Path $dir)) { continue }
Get-ChildItem -Path $dir -Filter "$Prefix-*.md" | ForEach-Object {
if ($_.BaseName -match ('^' + [regex]::Escape($Prefix) + '-(\d+)')) {
$n = [int]$Matches[1]
if ($n -gt $max) { $max = $n }
}
}
}
'{0:D3}' -f ($max + 1)
}
$nextPdr = Get-NextRecordNumber -Prefix 'PDR' -Dirs @(
$PdrDraftsDir,
(Join-Path $RepoRoot "docs/adlc/memory/pdr")
)
$pdrCount = if (Test-Path $PdrDraftsDir) { (Get-ChildItem -Path $PdrDraftsDir -Filter 'PDR-*.md').Count } else { 0 }
if ($Json) {
Write-Output (@{ REPO_ROOT=$RepoRoot; PDR_DRAFTS_DIR=$PdrDraftsDir; PRD_FILE=$PrdFile; next_pdr=$nextPdr; pdr_count=$pdrCount } | ConvertTo-Json)
} else {
Write-Output "[INFO] product-specify setup"
Write-Output " REPO_ROOT: $RepoRoot"
Write-Output " Next PDR: PDR-$nextPdr"
Write-Output " Existing PDRs: $pdrCount"
}
SKILL.md
---
name: product-specify
description: Use when you want guided trade-off analysis, multi-option comparison, or structured product decision facilitation before documenting. Class boots only suggest capture — they never write drafts; running this skill writes the lightweight PDR draft.
disable-model-invocation: true
---
# 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
```bash
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):
```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**:
```markdown
## 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**:
```markdown
## 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:
| Pattern | Detection | Action |
|---------|-----------|--------|
| Shared Personas | Same user type in multiple areas | Note for cross-area metadata |
| Priority Tensions | Areas prioritize differently | ⚠️ Flag potential conflict |
| Feature Overlap | Similar features in different areas | ⚠️ Flag for consolidation |
| Metric Conflicts | Same metric, different targets | ⚠️ Flag for alignment |
### 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).
```markdown
---
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**:
```markdown
# 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
```markdown
## 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
| Rationalization | Reality |
|-----------------|---------|
| "Let's just write the PRD directly." | PRDs without PDRs lack traceable rationale. Decisions become undocumented assumptions. |
| "We already know what to build." | Even "obvious" decisions have alternatives. Documenting them prevents future reversal. |
| "Exploration takes too long." | A 10-minute discussion now prevents weeks of rework later. |
## 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