product-clarify
Skill145 starsChanged 23 days agoMITView on GitHub
Use when PDRs need refinement, conflict detection, or approval to Accepted status before /product-implement.
In this repository48 other files it gives its agents.
- architect-analyzeSkill
- architect-bootSkill
- architect-clarifySkill
- architect-implementSkill
- architect-initSkill
- architect-specifySkill
- writing-skillsSkill
- change-bootSkill
- change-clarifySkill
- change-initSkill
- change-publishSkill
- change-specifySkill
- evals-analyzeSkill
- evals-clarifySkill
- evals-implementSkill
- evals-initSkill
- evals-specifySkill
- evals-validateSkill
- factory-cleanSkill
- factory-initSkill
- factory-intentSkill
- factory-learnSkill
- factory-missionSkill
- factory-orchestratorSkill
- factory-queueSkill
- factory-releaseSkill
- factory-reviewSkill
- factory-runbookSkill
- factory-setupSkill
- factory-ticketsSkill
- mission-briefSkill
- product-analyzeSkill
- product-bootSkill
- product-implementSkill
- product-initSkill
- product-roadmapSkill
- product-specifySkill
- team-bootSkill
- team-constitutionSkill
- team-diagnoseSkill
- team-discoverSkill
- team-initSkill
- team-levelupSkill
- team-repairSkill
- team-setupSkill
- team-skillsSkill
- workspaceSkill
- tech-radar-bootSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
After /product-specify or /product-init to refine initial PDRs
- Very specific: line 20
Before /product-implement to approve PDRs (required — implement skips non-Accepted)
- Very specific: line 26
No PDRs exist (use /product-specify or /product-init first)
- Very specific: line 50
Check if the draft being reviewed uses the lightweight draft template (indicated by presence of type, evidence, source, revisit-when fields …
- Distinctive: line 56
Read the draft's captured fields (Context, Decision, Rejected Alternatives, Reason)
- Distinctive: line 66
If already full format, proceed with normal review.
- Distinctive: line 70
Check each PDR against standards:
- Distinctive: line 113
HIGH: No alternatives, missing consequences
- Very specific: line 119
Write every clarification in Simplified Technical English (short sentences, one idea each, active voice, imperative asks, named referents, …
- Distinctive: line 147
Summarize changes: after each answer
- Distinctive: line 235
Preserve original intent: when updating wording
- Distinctive: line 240
Ask one question at a time
≈ “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.
Files
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-specifyor/product-initto refine initial PDRs - Before
/product-implementto 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-specifyor/product-initfirst)
Execution Steps
Phase 1: Load PDRs
- Run setup script:
sh: scripts/bash/setup-product-clarify.sh [--json]
ps: scripts/powershell/setup-product-clarify.ps1- Read all PDR files from
{REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md - Read constitution from
{REPO_ROOT}/docs/adlc/memory/constitution.md, falling back to legacy{REPO_ROOT}/.adlc/memory/constitution.md(dual-read), if either exists - 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:
- Read the draft's captured fields (Context, Decision, Rejected Alternatives, Reason)
- 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
- Enrich from session context (add details the lightweight draft may have omitted)
- Present the enriched draft for review
If already full format, proceed with normal review.
Phase 2: PDR Quality Analysis
Check each PDR against standards:
| Dimension | Check | Severity if Missing |
| 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 |
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
- Conflicting Decisions: Same concept, different decisions across PDRs
- Missing Dependencies: PDRs that should reference each other
- Terminology Drift: Same concept named differently
- 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
Write every clarification in Simplified Technical English (short sentences, one idea each, active voice, imperative asks, named referents, plain words). Read the contract at skills/authoring/references/ste-rules.md before drafting questions.
Count crossed boundaries (record, lane, team, now) for each gap. See the tier rule in the shared reference:
- 0–1 boundaries: present one clarification at a time in plain STE prose, using this format, however severe the gap:
## Clarification [N]: PDR-XXX — [Gap Type]
**Context**: [One STE sentence quoting the PDR content]
**Gap**: [One STE sentence describing the missing element]
**Question**: [One direct imperative STE question]
**Suggested Options**:
- **A**: [Option text]
- **B**: [Option text]
- **C**: [Custom response]- 2 or more boundaries: draw the full ASCII decision map from the reference (WHAT/WHY, crossed boundaries, reach fan-out, candidates × discriminating axes, IF-UNDECIDED). Render unknown gaps as
?slots, never prose complaints.
Rules:
- Present one clarification at a time
- Prioritize by severity — CRITICAL/HIGH first (severity orders questions; it never upgrades a 0–1-boundary item to a map)
- Limit to 5 clarifications per session
- Allow user to skip non-critical clarifications
- Summarize changes after each answer
Phase 6: Constitution Violations (if any)
For Duplicates:
## Constitution Duplication Detected
**PDR**: PDR-XXX — [Title]
**Constitution Principle**: §[Section] — [Principle]
**Options**:
| Option | Action |
|--------|--------|
| A | Remove PDR |
| B | Convert to Reference |
| C | Add Context |
| D | Extend |For Violations (⭐ RECOMMENDED: Amend Constitution):
## Constitution Violation Detected ⭐
**⭐ RECOMMENDED: A. Amend Constitution**
Update constitution §[Section] to accommodate this decision.
**Alternatives**:
B. Override in PDR — Document justification
C. Revise PDR — Change decision to comply
D. Remove PDR — Delete and follow constitutionPhase 7: Update PDR Files
- Apply clarifications per-file
- Update status where applicable
- Update "Last Updated" timestamps
- Regenerate
pdr/pdr.mdindex — callgenerate_pdr_index draftsfrompdr-lib.sh(orGenerate-PdrIndex draftsfrompdr-lib.ps1). This uses a frontmatter-primary + heading-fallback parser that handles both H2 and H3 metadata, preventing the blank-row bug.
Phase 8: PDR Approval ⭐
Critical: /product-implement only processes PDRs with Accepted status.
## PDR Approval ⭐
**Total PDRs**: [N]
**Status Distribution**:
- Accepted: [N]
- Proposed: [N]
- Discovered: [N]
**Options**:
| Option | Action |
|--------|--------|
| A | Accept All — Change Proposed/Discovered → Accepted |
| B | Review Specific — Select individual PDRs |
| C | Defer — Keep current status |Bulk approval (Option A):
## Confirm Bulk Approval
Change [N] PDRs to Accepted?
| PDR | Current | New |
|-----|---------|-----|
| PDR-001 | Proposed | Accepted |
| PDR-002 | Discovered | Accepted |Post-approval:
## PDRs Approved
**Ready for Implementation**:
- Accepted PDRs: [N]
- Pending: [N]
Run `/product-implement` to generate PRD.md.Key Rules
Non-Destructive Refinement
- Never delete existing PDRs without explicit user approval
- Preserve original intent when updating wording
- Add, don't replace consequences and alternatives
- Mark changes with updated timestamps
Focused Clarification
- Ask one question at a time
- Make questions specific and answerable
- Provide suggested options when possible
- Respect user's time
Constitution Authority
- Constitution violations are always flagged
- PDRs cannot override MUST principles without justification
- Suggest constitution updates if conflict is systemic
Configuration
REPO_ROOT— resolved by the setup script (searches upward for.adlc); always use{REPO_ROOT}-anchored paths, never bare relative paths. When running helpers from zsh, source thescripts/bash/file underbash -coremulate -L sh: the scripts rely onBASH_SOURCE[0]for path resolution and will not locate helpers under zsh.PDR_DRAFTS_DIR—{REPO_ROOT}/.adlc/drafts/pdrPDR_INDEX—{REPO_ROOT}/.adlc/drafts/pdr/pdr.mdCONSTITUTION—{REPO_ROOT}/docs/adlc/memory/constitution.md(legacy.adlc/memory/constitution.mdfallback)move_pdr/next_record_numberaccept bare IDs (8), zero-padded IDs (008), and full suffixed stems (008-amendment-2): thePDR-prefix is optional and callers must never pre-strip it.
12-Factor Alignment
- Factor III (Mission Definition): Ensures product mission is well-defined before execution
- Factor VII (Quality Gates): Applies human judgment before automated generation
Common Rationalizations
| Rationalization | Reality |
| "The PDRs look fine — let's skip clarify." | Implement will skip non-Accepted PDRs, silently dropping decisions from the PRD. |
| "I'll just accept all at once." | Bulk accept without review risks embedding bad decisions into the PRD. |
| "A warning on constitution is basically okay." | Constitution violations are CRITICAL because they undermine product coherence. |
Red Flags
- Skipping the approval step — without Accepted status, implement ignores the PDR.
- Accepting without reading — defeats the purpose of the quality gate.
- Not flagging cross-PDR conflicts — inconsistent PDRs produce an incoherent PRD.
Verification
- All PDR files read and inventoried
- Quality checklist applied to each PDR
- Cross-PDR consistency verified
- Constitution alignment checked
- Gaps identified and prioritized
- Clarifications applied per-file
pdr.mdindex regenerated- Approval phase completed (Accept/Review/Defer)
- Accepted PDRs have status "Accepted" in their files
- No duplicate or missing PDR IDs
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
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.

