agentleFS
tikalktikalk/adlc-team-skills/skills/product/product-analyze/SKILL.md

product-analyze

Skill145 starsChanged 23 days agoMITView on GitHub

Use when checking PDR↔PRD consistency after /product-implement or periodically to detect drift, PDR quality issues, cross-PDR conflicts, and staleness.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After /product-implement to validate generated PRD

    line 27
  2. Very specific:

    After /product-clarify to verify refinements

    line 28
  3. Distinctive:

    Before feature development to ensure product is solid

    line 29
  4. Very specific:

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

    line 34
  5. Distinctive:

    Run it over the PRD and any product artifact that carries diagrams.

    line 135

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

product-analyze

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

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:

DimensionCheckSeverity
ContextProblem clearly statedMEDIUM
DecisionActionable, testableHIGH
ConsequencesPositive AND negativeHIGH
Success MetricsDefined with targetsHIGH
AlternativesAt least 2 with neutral trade-offsHIGH
ConstitutionAligns with visionCRITICAL

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 ElementExpected in PRDSection
Problem decisionProblem statement3
Persona decisionPersonas6
Scope decisionRequirements / Out of Scope7 / 9
Metric decisionSuccess Metrics5
Business ModelOverview2
NFR decisionNon-Functional Requirements8

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:

Invoke the `architect-clarify` skill to run the shared mermaid validator

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:

RuleMeaning
M001-fence-not-closedthe ```mermaid block is never closed
M002-unknown-diagram-typethe type keyword is outside the known set — review it, never a false HIGH
M003-missing-diagram-typethe block declares no diagram type at all
M004-empty-blockthe block carries no diagram content — comments and directives do not count
M005-empty-bodya 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-headerthe 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-diagramthe 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-diagramthe 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-keywordgraph 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

SeverityCriteria
CRITICALConstitution violation, major requirement undocumented
HIGHPDR→PRD drift affecting requirements, conflicting PDRs
MEDIUMIncomplete consequences, staleness, terminology drift
LOWStyle improvements, minor documentation gaps

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 — the architect-clarify skill validator (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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.