product-analyze

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

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:

| 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:

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:

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:

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:

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

Phase 9: Generate Report

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