Product Clarify

product-clarify

What this skill does

Reviews existing PDRs for quality gaps, asks targeted clarification questions, and promotes approved PDRs to Accepted status. This is the quality gate before PRD generation.

Input: Individual PDR-*.md files in .adlc/drafts/pdr/ (status Proposed or Discovered)

Output: Updated PDR-*.md files (status Accepted where approved), regenerated pdr.md index

When to use

• After /product-specify or /product-init to refine initial PDRs
• Before /product-implement to approve PDRs (required — implement skips non-Accepted)
• Periodic PDR review before milestones
• Resolving inconsistency flags from cross-feature-area analysis

When NOT to use

• No PDRs exist (use /product-specify or /product-init first)

Execution Steps

Phase 1: Load PDRs

1. Run setup script:

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

2. Read all PDR files from {REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md
3. Read constitution from {REPO_ROOT}/docs/adlc/memory/constitution.md, falling back to legacy {REPO_ROOT}/.adlc/memory/constitution.md (ADR-401 dual-read), if either exists
4. Build inventory:

| PDR | Title | Status | Category |
|-----|-------|--------|----------|
| PDR-001 | Target Market | Proposed | Problem |
| PDR-002 | Primary Persona | Proposed | Persona |

Step 0: Detect Lightweight Draft Format

Check if the draft being reviewed uses the lightweight draft template (indicated by presence of type, evidence, source, revisit-when fields in frontmatter and ## Rejected Alternatives / ## Reason body sections without the full formal template sections).

If lightweight:

1. Read the draft's captured fields (Context, Decision, Rejected Alternatives, Reason)
2. Transform to full formal template:
   • ADR: full MADR format with Decision Drivers, Considered Options, Pros/Cons, Constitution Alignment, Related ADRs
   • PDR: full PDR format with Market Forces, Consequences, Alternatives Considered, Links
   • ChDR: full ChDR format with Issue Links, Commits, Consequences, Evidence
   • CDR: full CDR format with Context Type, Target Module, Descriptor, Evidence
   • EVAL: full eval format with Error Analysis, Pass/Fail Examples, Implementation Notes
3. Enrich from session context (add details the lightweight draft may have omitted)
4. Present the enriched draft for review

If already full format, proceed with normal review.

Phase 2: PDR Quality Analysis

Check each PDR against standards:

Quality checklist:

• Clear context explaining the problem/opportunity
• Explicit, actionable decision statement
• Positive AND negative consequences documented
• At least 2 alternatives with neutral trade-offs (not "rejected because")
• Success metrics defined
• Risks identified with mitigation strategies
• Valid status value
• No conflicts with other PDRs
• Alignment with constitution/vision principles

Phase 3: Cross-PDR Consistency

1. Conflicting Decisions: Same concept, different decisions across PDRs
2. Missing Dependencies: PDRs that should reference each other
3. Terminology Drift: Same concept named differently
4. Priority Conflicts: One PDR says B2B, another assumes B2C

Phase 4: Gap Identification

Generate gap report:

## PDR Clarification Report

| PDR | Title | Gap Type | Severity |
|-----|-------|----------|----------|
| PDR-001 | [Title] | Missing alternatives | HIGH |
| PDR-002 | [Title] | Incomplete consequences | MEDIUM |

Severity:

• CRITICAL: Constitution violations, missing decision statement, no success metrics
• HIGH: No alternatives, missing consequences
• MEDIUM: Incomplete risks, unclear context
• LOW: Minor phrasing

Phase 5: Interactive Refinement

For each gap, present one clarification at a time:

## Clarification [N]: PDR-XXX — [Gap Type]

**Current State**:
[Quote current PDR content]

**Gap Identified**:
[Explain what's missing]

**Question**:
[Specific question]

**Suggested Options**:
| Option | Description |
|--------|-------------|
| A | [Option A] |
| B | [Option B] |
| C | [Custom response] |

Rules:

• Present one clarification at a time
• Prioritize by severity — CRITICAL/HIGH first
• Limit to 5 clarifications per session
• Allow user to skip non-critical clarifications
• Summarize changes after each answer