---
name: product-analyze
description: Use when checking PDR↔PRD consistency after /product-implement or periodically to detect drift, PDR quality issues, cross-PDR conflicts, and staleness.
disable-model-invocation: true
---

# product-analyze

## What this skill does

Performs **read-only** product consistency analysis:

1. **PDR Quality** — completeness, clarity, standards compliance
2. **PDR→PRD Drift** — decisions not reflected in PRD
3. **PRD→PDR Drift** — PRD elements without supporting PDRs
4. **Cross-PDR Consistency** — conflicts between PDRs
5. **Staleness** — outdated references, placeholders, deprecated PDRs still referenced
6. **Mermaid Syntax** — invalid diagram blocks flagged with location + suggested patch (the mermaid detection pass)

**Output**: Structured markdown analysis report (no files modified)

## When to use

- After `/product-implement` to validate generated PRD
- After `/product-clarify` to verify refinements
- Before feature development to ensure product is solid
- Periodically to detect drift as product evolves

## When NOT to use

- No product artifacts exist (use `/product-init` or `/product-specify` first)
- You want to modify files (this is analysis-only)

## Execution Steps

### Phase 1: Load Artifacts

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

**Read**:
- `docs/adlc/product/PRD.md` (legacy repo-root `PRD.md` fallback — dual-read)
- `{REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md` (individual PDR files)
- `{REPO_ROOT}/docs/adlc/memory/constitution.md`, falling back to legacy `{REPO_ROOT}/.adlc/memory/constitution.md` (dual-read; if either exists)

**Build inventory**:
```markdown
| Artifact | Path | Status |
|----------|------|--------|
| Product PRD | docs/adlc/product/PRD.md (legacy PRD.md fallback) | Found/Missing |
| Product PDRs | .adlc/drafts/pdr/ | [N] files |
| Constitution | docs/adlc/memory/constitution.md (legacy .adlc/memory fallback) | Found/Missing |
```

### Phase 2: PDR Quality Analysis

For each PDR file, check:

| Dimension | Check | Severity |
|-----------|-------|----------|
| Context | Problem clearly stated | MEDIUM |
| Decision | Actionable, testable | HIGH |
| Consequences | Positive AND negative | HIGH |
| Success Metrics | Defined with targets | HIGH |
| Alternatives | At least 2 with neutral trade-offs | HIGH |
| Constitution | Aligns with vision | CRITICAL |

### Phase 3: Inter-PDR Consistency

1. **Conflicting Decisions**: PDRs that contradict (e.g., B2B vs B2C)
2. **Missing Dependencies**: PDRs that should reference each other
3. **Terminology Drift**: Same concept named differently
4. **Strategy Coherence**: Problem/persona/metric alignment

### Phase 4: PDR→PRD Drift (Forward Sync)

For each PDR, check if decision appears in PRD:

| PDR Element | Expected in PRD | Section |
|-------------|-----------------|---------|
| Problem decision | Problem statement | 3 |
| Persona decision | Personas | 6 |
| Scope decision | Requirements / Out of Scope | 7 / 9 |
| Metric decision | Success Metrics | 5 |
| Business Model | Overview | 2 |
| NFR decision | Non-Functional Requirements | 8 |

### Phase 5: PRD→PDR Drift (Backward Sync)

1. **Requirements Without PDRs**: User stories without scope justification
2. **Personas Without PDRs**: Personas with no persona PDR
3. **Metrics Without PDRs**: Success metrics with no metric PDR
4. **Risks Without PDRs**: Risks without consequence documentation

### Phase 6: Staleness Detection

1. **Deprecated PDRs Still Referenced**: PRD references status "Deprecated"
2. **Placeholders**: `[TODO]`, `[TBD]`, `[PRODUCT_NAME]`, `[DATE]`
3. **Date Inconsistencies**: PDR dates older than PRD last-updated
4. **Orphaned References**: PDR IDs mentioned but file doesn't exist

### Phase 7: Mermaid Syntax Validation (the mermaid detection pass)

**Objective**: flag invalid Mermaid blocks in the PRD with a location and a suggested patch, so a broken diagram never ships unremarked.

**Run the shared validator** — it owns the rule set (canonical in `architect-clarify`; the rules are documented once, in the validator itself). Do not re-derive or restate the thresholds here:

```bash
sh: {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/mermaid-lint.sh --tsv <artifact>
```

Requires the `architect-clarify` skill (`adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify`). Exit code: `0` clean, `1` a HIGH (syntax-break) is present, `2` only MEDIUM (style) findings.

**Rule vocabulary** — the validator's own ids; severity travels with each finding, never inferred here:

| Rule | Meaning |
|------|---------|
| `M001-fence-not-closed` | the ` ```mermaid ` block is never closed |
| `M002-unknown-diagram-type` | the type keyword is outside the known set — review it, never a false HIGH |
| `M003-missing-diagram-type` | the block declares no diagram type at all |
| `M004-empty-block` | the block carries no diagram content — comments and directives do not count |
| `M005-empty-body` | a type is declared but no statement follows — mermaid renders it (an empty chart), so it is a MEDIUM style finding, never a syntax break; the finding sits on the type declaration |
| `M006-malformed-gantt-header` | the gantt block's first statement (comments and directives skipped) is neither a gantt key nor a task line — a malformed first statement is a syntax break (HIGH); a task-line-shaped statement is at most MEDIUM, never a false HIGH |
| `M007-malformed-sequence-diagram` | the sequenceDiagram's first statement (comments and directives skipped) is not a documented sequence statement — a `participant`, a message, or a keyword such as `title`, `autonumber`, `box`, `critical` or `break`; a statement matching none of those is a syntax break (HIGH) |
| `M008-malformed-entity-diagram` | the erDiagram's first statement (comments and directives skipped) carries a character mermaid's entity-name grammar rejects — a relation, an attribute block, or a bare name made of letters, digits, `_`, `-`, `.` and spaces is valid (mermaid parses a bare name as an isolated entity), so only an unparseable name is a syntax break (HIGH) |
| `M009-non-mandated-keyword` | `graph` used where the product mandate requires `flowchart` |

**Rules**:

- Run it over the PRD and any product artifact that carries diagrams.
- Fold its findings into the report verbatim — severity, location and suggested patch come from the validator; do not re-word or re-grade them.
- The pass is **read-only** (the lifecycle write scope lifecycle write scope): remediation belongs to `/product-implement` or a human, never to this skill.
- An unrecognised diagram type is MEDIUM, never HIGH — the rule set must not produce a false syntax break.
- A declared type with **no statement at all** still renders (an empty chart): the validator reports it MEDIUM (`M005-empty-body`), located on the type declaration — never a syntax break. Only a *malformed* first statement is HIGH.
- A mermaid comment (`%% …`) or directive (`%%{ … }%%`) is not content — the validator skips it wherever it reads a block's type or its first statement, so a comment-first diagram is valid.

### Phase 8: Severity Assignment

| Severity | Criteria |
|----------|----------|
| **CRITICAL** | Constitution violation, major requirement undocumented |
| **HIGH** | PDR→PRD drift affecting requirements, conflicting PDRs |
| **MEDIUM** | Incomplete consequences, staleness, terminology drift |
| **LOW** | Style improvements, minor documentation gaps |

### Phase 9: Generate Report

```markdown
## Product Analysis Report

### Analysis Summary
| Attribute | Value |
|-----------|-------|
| Mode | [Full/PDRs/Sections] |
| Files Analyzed | [List] |
| Analysis Date | [Current date] |

### Findings
| ID | Pass | Severity | Location | Summary | Recommendation |
|----|------|----------|----------|---------|----------------|
| A1 | PDR Quality | MEDIUM | PDR-003 | Missing success metrics | Add metrics section |
| B1 | Inter-PDR | HIGH | PDR-002, PDR-005 | Conflicting target markets | Resolve B2B vs B2C |
| C1 | PDR→PRD | HIGH | PRD:5 | Persona not in PRD | Update PRD section 5 |
| D1 | PRD→PDR | HIGH | PRD:6 | Feature has no PDR | Create PDR |
| F1 | Staleness | LOW | PRD:1 | [PRODUCT_NAME] placeholder | Fill product name |
| G1 | Mermaid Syntax | HIGH | PRD:42 (fence #3) | ` ```mermaid ` block has no content | add the diagram body, e.g. `flowchart TD / A[Start] --> B[End]` |

### Coverage Metrics
| Metric | Value |
|--------|-------|
| PDR Count | [N] |
| PRD Sections Complete | [N]/12 |
| PDR→PRD Coverage | [N]% |
| PRD→PDR Coverage | [N]% |

### Issue Distribution
| Severity | Count |
|----------|-------|
| CRITICAL | [N] |
| HIGH | [N] |
| MEDIUM | [N] |
| LOW | [N] |

### Next Actions
- **CRITICAL issues**: Resolve constitution violations before proceeding
  - Command: `/product-clarify`
- **HIGH PDR quality**: Address missing alternatives and consequences
  - Command: `/product-clarify`
- **PDR→PRD drift**: Update PRD to reflect PDR decisions
  - Command: `/product-implement --update`
- **PRD→PDR drift**: Create missing PDRs
  - Command: `/product-specify` or `/product-init`
```

## Key Rules

### Analysis Integrity
- **NEVER modify files** — this is read-only
- **NEVER hallucinate missing content** — report absences accurately
- **Prioritize constitution violations** — always CRITICAL
- **Use evidence-based findings** — cite specific locations
- **The Mermaid pass writes nothing** — it reports; `/product-implement` or a human remediates (the lifecycle write scope)

### Reporting Standards
- **Limit to 50 findings** — aggregate overflow in summary
- **Include location** — always cite file or section
- **Provide actionable recommendations** — each finding gets a fix suggestion
- **Calculate coverage metrics** — quantify completeness

## Configuration

- `PDR_DRAFTS_DIR` — `{REPO_ROOT}/.adlc/drafts/pdr`
- `PRD_FILE` — `{REPO_ROOT}/docs/adlc/product/PRD.md`
- `CONSTITUTION` — `{REPO_ROOT}/docs/adlc/memory/constitution.md` (legacy `.adlc/memory/constitution.md` fallback)
- `MERMAID_LINTER` — `{REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/mermaid-lint.sh` (canonical in `architect-clarify`; requires that skill to be installed)

## 12-Factor Alignment

- **Factor IX (Verification-First)**: Validates artifacts before downstream work
- **Factor XI (Directives as Code)**: Checks version-controlled directive quality

## Verification

- [ ] All artifacts loaded and inventoried
- [ ] PDR quality checklist applied to each file
- [ ] Cross-PDR consistency verified
- [ ] Bidirectional drift detection completed
- [ ] Staleness scan performed
- [ ] Mermaid syntax validated (shared linter run; every broken block carries severity, location and a patch)
- [ ] Severities assigned correctly
- [ ] Report structured with findings table
- [ ] Coverage metrics calculated
- [ ] Next actions recommended with commands
- [ ] Zero files modified