PRD Flaw Checker

A structured PRD analysis skill for OpenCode that uses first-principles thinking, consistency cross-validation, and ambiguity detection to uncover logical gaps, contradictions, vague descriptions, and open issues in Product Requirements Documents. It interactively collects clarifications from users and writes them back directly into the PRD.

中文文档

Overview

PRD Flaw Checker performs a three-round deep analysis on PRD documents.

Naming note — The internal skill identifier (as registered in SKILL.md) is bmad-prd-analyze, but the directory name is prd-flaw-checker. The directory name and skill name are independent; the skill name is what OpenCode uses to route triggers, while the directory name is just where the files live.

| Round | Analysis Type | Focus | |-------|---------------|-------| | A | First Principles | Core problem identification, assumption auditing, derivation chain validation, means-vs-ends confusion | | B | Consistency | FR-UJ alignment, terminology consistency, priority alignment, scope conflicts, dependency completeness | | C | Ambiguity Detection | Fuzzy adjectives, open-ended descriptions, implicit assumptions, missing acceptance criteria |

After analysis, findings are ranked by severity (Critical / High / Medium / Low) and presented to the user for interactive clarification. Confirmed fixes are then automatically written back into the PRD document.

Features

• Three-Round Parallel Analysis — Three sub-agents analyze the PRD simultaneously from different angles.
• Interactive Clarification — Critical and High-severity findings are presented as structured questions for the user to resolve.
• Auto Write-Back — Confirmed clarifications are directly edited into the PRD using the edit tool, with status tracking.
• Multi-Round Iteration — After each round of analysis and write-back, optionally start a new round until the document quality meets expectations.
• Severity Classification — All findings are categorized as Critical, High, Medium, or Low.
• Source Extraction — Works on a structured extract of the PRD rather than loading the full document into context.

Workflow

Stage 1: Locate PRD Document (+ optional addendum.md)
    ↓
Stage 2: Source Extraction (structured summary, full PRD not loaded)
    ↓
Stage 3: Three-Round Parallel Analysis (sub-agents A, B, C)
    ↓
Stage 4: Aggregate Findings (deduplicated, ranked by severity)
    ↓
Stage 5: Interactive Clarification (batched questions, Critical + High only)
    ↓
Stage 6: Write Back to PRD (auto-edit, status-tracked)
    ↓
Stage 7: Output Final Summary
    ↓
Stage 8: Ask to Continue (next round or end)

A finding is treated as confirmed only when you explicitly select one of the offered options or provide a free-text answer. Skipped or deferred items are marked [DEFERRED] in the report and not written back to the PRD.

Requirements

• OpenCode with skill loading support.
• Built-in tools used by the skill: task (subagent dispatch), question (interactive clarification), edit (PRD write-back).
• No external packages or network access required.

Installation

1. Copy this entire directory (prd-flaw-checker/) into your OpenCode skills directory. Common locations:

   • Project-level: .agents/skills/prd-flaw-checker/
   • Project-level (legacy): skills/prd-flaw-checker/
   • Global: ~/.config/opencode/skills/prd-flaw-checker/

2. Verify the resulting layout:

   prd-flaw-checker/
   ├── SKILL.md
   ├── references/
   │   ├── first-principles.md
   │   ├── consistency-checklist.md
   │   └── ambiguity-patterns.md
   ├── assets/                  (optional, default empty)
   ├── README.md                (this file)
   └── README_zh.md

3. Restart OpenCode for the skill to take effect.

The directory can be renamed freely — OpenCode only reads the name: field inside SKILL.md to identify the skill.

Usage

1. Have a PRD document ready (e.g., prd.md). Optionally, place a related addendum.md in the same directory — it will be loaded alongside the PRD for cross-reference analysis.

2. Trigger the skill via any of these natural language prompts (OpenCode matches them against the description field in SKILL.md):

   • "Please review this PRD for logical flaws."
   • "Which parts of this requirements document are unclear? Find ambiguous expressions."
   • "We're about to hold a review meeting — can you check this product proposal using first principles?"
   • "Do the rules for Feature A and Feature B in this PRD contradict each other? Check for consistency."
   • "As a developer, I want to know if this spec is testable and what boundary conditions are missing."

3. Confirm the PRD file path when prompted. If the path is not provided, the skill scans the working directory for prd.md, *prd*.md, and similar candidates, and asks you to choose.

4. Review the aggregated findings and answer the batched clarification questions (Critical and High severity only).

5. The skill writes your confirmed answers back into the PRD via the edit tool. Medium and Low findings are listed in the final report but are not asked interactively — request them explicitly with "show me the Medium/Low items" if you want to address them.

6. At the end of each round, choose whether to start another round. The skill itself has no automatic stopping criterion; iteration ends when you say so.

How It Works

First Principles Analysis (references/first-principles.md)

• Deconstructs the PRD to its core problem and fundamental assumptions.
• Audits each assumption: verified, unverified, or falsifiable.
• Validates the derivation chain from problem → solution → features → FRs.
• Identifies means-vs-ends confusion (mistaking "how" for "why").

Consistency Check (references/consistency-checklist.md)

• Cross-references FRs with User Journeys (coverage gaps).
• Checks terminology consistency across sections (glossary alignment).
• Validates priority alignment with strategic goals.
• Identifies scope conflicts (Non-Goals vs FRs, MVP boundaries).
• Checks dependency completeness and NFR consistency.

Ambiguity Detection (references/ambiguity-patterns.md)

• Scans for fuzzy adjectives (e.g., "reasonable", "fast", "user-friendly").
• Detects open-ended descriptions missing quantitative boundaries.
• Surfaces implicit assumptions that need explicit declaration.
• Flags functional requirements lacking testable acceptance criteria.

Write-Back Strategy

| Finding Type | Write-Back Action | |--------------|-------------------| | Fuzzy adjective | Replace with confirmed specific value | | Missing quantitative boundary | Insert specific metric, threshold, or boundary condition | | Implicit assumption | Make explicit as [ASSUMPTION: ...] inline annotation | | Missing acceptance criteria | Add verifiable acceptance conditions under the FR | | Terminology inconsistency | Unify to confirmed standard term | | Priority / scope conflict | Correct based on user confirmation; mark unresolved with [CLARIFY: ...] | | Derivation gap | Insert missing intermediate reasoning steps | | Missing condition | Add specific trigger condition or branch description |

Severity Levels

Every finding is tagged with one of four severities:

| Level | Definition | Interactive? | |-------|------------|--------------| | Critical | Blocks release or invalidates the PRD's core value proposition. Must be resolved before sign-off. | Asked first, one batch | | High | Causes significant rework, contradiction, or testability failure. Should be resolved before development. | Asked after Critical, one batch | | Medium | Causes ambiguity that may lead to misimplementation. Should be clarified during design. | Reported only, ask on request | | Low | Stylistic, redundant, or minor clarity issues. Nice to fix. | Reported only, ask on request |

Structured Question Format

Each interactive question contains:

• ID — e.g. A-03 (round letter + sequence).
• Severity — Critical / High.
• Location — PRD section and line range.
• Evidence — verbatim quote from the PRD.
• Question — what is being clarified.
• Options — 2–4 multi-choice candidates inferred from context, plus an "Other (specify)" option for free-text input.

Questions are presented in batches grouped by severity (all Critical together, then all High) so you can answer them efficiently in one pass.

Example Output

A typical finding presented to the user:

[A-03]  Severity: High
Location: §3.2 User Authentication (lines 142–148)
Evidence: "登录响应应该比较快"
Issue:    "比较快" is a fuzzy adjective with no quantitative boundary.
Question: What is the target P99 response time for login?
Options:
  1. ≤ 200 ms
  2. ≤ 500 ms
  3. ≤ 1 s
  4. Other (please specify)

Output Language

• All skill output (questions, summaries, write-back annotations) is produced in Chinese by default, as defined in SKILL.md.
• Original PRD text and the user's own prompts are preserved verbatim regardless of their language.
• To run the skill fully in English, edit the prompts inside SKILL.md and the three references/*.md files; no other changes are needed.

File Structure

prd-flaw-checker/
├── SKILL.md                           # Main skill definition and workflow (Chinese)
├── references/
│   ├── first-principles.md            # First principles analysis framework
│   ├── consistency-checklist.md       # Cross-reference consistency checklist
│   └── ambiguity-patterns.md          # Ambiguity and fuzziness detection patterns
├── assets/                            # Static assets (default empty)
├── README.md                          # This document (English)
└── README_zh.md                       # Chinese documentation

License

MIT License. See LICENSE for details.