# PRD Quality Rubric

A judgment rubric for the validator subagent. Walk the PRD with these dimensions in mind and write substantive findings — not box-ticking. The goal is a review that tells the user whether this PRD is _good_, not whether it has the right section headers.

This rubric folds XiaoMa's mechanical quality standard (the retired `xiaoma-validate-prd` rubric) into the holistic judgment frame. Some dimensions are forgiving and stakes-calibrated; others are unforgiving and downstream-critical. **Measurability, Traceability, SMART (FR/NFR), and Domain Compliance are the dimensions that silently break downstream work** — story creation, architecture, and regulatory sign-off all source-extract from them. Judge those hardest. Be specific everywhere — cite locations, quote phrases, name what's missing. Abstract criticism is failure of nerve.

Most PRDs do not need every dimension scrutinized equally. Calibrate to the agreed stakes, the PRD's shape (consumer product, internal tool, regulatory update, technical capability spec), and what the PRD itself is trying to do.

## How to use this rubric

1. Read the full PRD (and addendum.md if present) before writing anything.
2. For each dimension below, form a judgment — _strong / adequate / thin / broken_ — backed by specifics from the PRD.
3. Write findings only where they add information. A `strong` dimension may need no findings; a `broken` one needs concrete, fixable ones.
4. Severity ranks impact on the PRD's usefulness, not how easy the fix is. A vague Vision statement is _critical_ even though it's a one-paragraph fix; a glossary drift might be _low_ even though it appears in many places. The unforgiving dimensions (Measurability, Traceability, SMART, Domain Compliance) bias toward _blocker/critical_ when they break, because downstream consumers cannot route around them.
5. Mark a dimension _n/a_ when the PRD's shape genuinely doesn't need it (e.g. Project-Type Fit for a one-off internal note) and say why — don't penalize a PRD for skipping work it didn't need.
6. The overall verdict is your synthesis — 2–3 sentences that name what holds up and what's at risk. Earn it with the dimension judgments.

## Output format

Write findings to `{doc_workspace}/review-rubric.md`:

```markdown
# PRD Quality Review — {prd_name}

## Overall verdict

[2–3 sentences. What holds up, what's at risk. Earned by the dimension judgments below.]

## Decision-readiness — [strong | adequate | thin | broken]

[1–3 paragraphs of judgment with specific PRD locations.]

### Findings

- **[blocker|critical|high|medium|low]** [Title] (§ location) — [Note]. _Fix:_ [suggested fix].

## Substance over theater — [verdict]

...

(repeat for each dimension; mark n/a dimensions explicitly with a one-line reason)

## Mechanical notes

[Glossary drift, ID continuity, broken cross-refs, Assumptions Index roundtrip, frontmatter completeness. Lighter weight — these matter for downstream but don't drive the overall verdict.]
```

## The dimensions

### 1. Decision-readiness

Can a decision-maker act on this PRD? Are the trade-offs surfaced honestly, or has the PRD smoothed everything to neutral? Would someone pushing back find their objection acknowledged or dodged?

Look for:

- Decisions that are stated as decisions, not buried as "considerations."
- Trade-offs named with what was given up, not just what was chosen.
- Open Questions that are actually open — not rhetorical questions with an answer in the next sentence.
- `[NOTE FOR PM]` callouts at real tensions, not at safe checkpoints.

Red flag: a PRD where every choice "balances" everything, every NFR is "important," every persona "values" the product.

### 2. Substance over theater

Is the content earned, or is it furniture? Distinguish:

- **Persona theater** — Personas that don't drive a single decision in the PRD. More than four personas. Personas whose only function is to make the PRD look thorough.
- **Innovation theater** — claimed novelty that isn't novel. Differentiation sections written because the template had one, not because Discovery surfaced something.
- **NFR theater** — copied boilerplate ("system must be scalable / secure / reliable") without product-specific thresholds.
- **Vision theater** — a Vision statement that could swap into any PRD in this category without change.

Flag what reads like furniture, even if it's well-written furniture.

### 3. Information density

Is every line carrying weight, or is the PRD padded with slogans and connective filler? This is where a polished-looking document hides an empty one.

What good looks like: a concrete Executive Summary anchored in metrics rather than aspiration; dense FR/NFR bullets; almost no marketing fluff.

What broken looks like: a slogan-driven summary, and roughly eight or more fluff phrases per hundred lines. Detection signals — phrases like "打造", "业界领先", "一站式", "赋能", "数字化转型", "智能化", "全方位", or English equivalents like "the system will allow", "it is important to note", "in order to". A handful across a long PRD is _thin_; a summary that reads like a pitch deck is _broken_. The fix is concrete: rewrite the Executive Summary around real metrics and cut the connective filler.

### 4. Strategic coherence

Does the PRD have a thesis? Do the features serve a unified arc, or is it a list of capabilities someone wanted?

Look for:

- A stated thesis the PRD bets on (problem framing, user insight, market move).
- Feature prioritization that follows from the thesis — not from "what's easy first."
- Success Metrics that validate the thesis, not metrics that just measure activity (DAU/MAU when the thesis is about engagement quality is a tell).
- Counter-metrics named when Success Metrics exist.
- Coherent MVP scope kind — problem-solving, experience, platform, or revenue — with scope logic that matches.

Red flag: a PRD that reads as a backlog with section headings.

### 5. Brief coverage

Did the PRD actually consume its upstream inputs, or did it quietly drop them? Every "required" field from the product brief / upstream input contract should map into a PRD section.

What good looks like: every required upstream field is represented somewhere in the PRD; no orphaned `TBD` markers standing in for content that was supposed to be carried forward.

What broken looks like: required brief fields that never made it in, or a pile of unresolved `TBD: <field>` markers. One or two open TBDs on a draft is _adequate_; missing required inputs is _broken_ because the PRD is answering a different question than the one it was commissioned for. The fix is to complete the missing fields or convert each TBD into a real decision or an explicit `[ASSUMPTION]`.

### 6. Measurability

Would an engineer reading this PRD know what "done" looks like for each FR, and what threshold each NFR must hit? This is one of the unforgiving, downstream-critical dimensions — story creation leans on it hardest. Be unforgiving here.

What good looks like: every FR phrased as a capability a named actor can perform ("[Actor] can [capability]"); every NFR carrying a metric, a threshold, a measurement method, and a window (e.g. "p95 latency < 200ms under 1k concurrent users, measured at the API gateway").

What broken looks like: FRs and NFRs leaning on subjective adjectives — "easy", "fast", "simple", "intuitive", "user-friendly", "responsive", "quick", "efficient", or Chinese equivalents like "快速", "易用", "简单", "高效", "流畅", "稳定", "良好", "显著", "多个", "若干" — without numbers behind them. Any NFR with no measurement method, or any NFR that is a bare subjective adjective, drags the dimension toward _broken_. Flag "system handles X gracefully", "reasonable performance", "user-friendly" — every one. For non-functional sections (UX, performance, security), demand bounds, not adjectives. The fix is to add baseline + target + measurement + window per NFR and rewrite subjective FRs around verifiable outcomes.

### 7. SMART (FR / NFR)

Beyond raw measurability, is each requirement Specific, Measurable, Attainable, Relevant, and Traceable — and is it _atomic_? Compound requirements are the main failure mode here and the main reason a clean-looking FR explodes into ambiguity at story-creation time. This is one of the unforgiving, downstream-critical dimensions.

What good looks like: one actor, one verb, one object per FR; NFRs that are individually attainable and tied to a real need.

What broken looks like: compound FRs that smuggle multiple actions behind connectives — "且", "并", "同时", "以及", "并且", or "and … and" — or a single FR spanning two or more data objects. More than a few compound or unattainable requirements is _broken_. The fix is to split compound FRs along Actor / Verb / Object / Channel axes so each becomes independently testable and traceable.

### 8. Implementation leakage

Is the PRD describing _what_ and _why_, or has it leaked into _how_? Technology proper nouns in the problem, vision, journey, and functional sections are a tell that solutioning has bled upstream into the product definition.

What good looks like: capability-level language throughout the vision, success criteria, user journeys, and functional requirements — no library, framework, datastore, or protocol names where a capability belongs.

What broken looks like: terms such as Redis, PostgreSQL, MongoDB, MySQL, Kafka, RabbitMQ, JWT, OAuth, WebSocket, React, Vue, Angular, Spring, Django, Express, Docker, Kubernetes, AWS, GCP, Azure, gRPC, or GraphQL appearing inside the vision, success-criteria, journey, or functional sections. A leak or two confined to an explicitly technical Project-Type section is tolerable; any leak in vision / success / journeys / FRs is a real problem. The fix is to restate the leaked term as a capability, or relocate genuinely load-bearing technical facts to the Non-Functional / Project-Type sections.

### 9. Done-ness clarity

Would an engineer know what "done" looks like beyond the per-FR metrics — at the acceptance level?

Look for:

- FRs with at least one testable consequence each — a verifiable condition or measurable outcome.
- Acceptance criteria implied or explicit. Sometimes the FR's consequences carry this; sometimes the PRD genuinely needs an Acceptance section.
- For non-functional sections (UX, performance, security): bounds, not adjectives.

This complements Measurability — Measurability judges whether each requirement is stated in verifiable terms; Done-ness judges whether the PRD as a whole tells the team when to stop.

### 10. Scope honesty

Are omissions explicit, or is the reader meant to infer them?

Look for:

- A Non-Goals section where it would do real work — and `[NON-GOAL for MVP]` callouts where omissions could be silently assumed.
- `[ASSUMPTION: …]` tags on inferences the user didn't directly confirm, indexed at the end.
- `[NOTE FOR PM]` callouts at deferred decisions and unresolved tensions.
- De-scoping proposed honestly, not done silently.

Open-items density: count Open Questions + `[ASSUMPTION]` + `[NOTE FOR PM]` callouts relative to stakes. High counts on a low-stakes PRD is fine; high counts on a green-light-to-build PRD is a blocker.

### 11. Domain compliance

For regulated or high-complexity domains, are the domain-specific sections present and substantive — or has the PRD treated a regulated product like a generic CRUD app? This is one of the unforgiving, downstream-critical dimensions: a missing regulatory section is not a style issue, it is a liability.

Detect the domain from frontmatter or §1 signals and check it against `assets/domain-complexity.csv`. For any domain that file marks **high** complexity — healthcare, fintech, govtech, aerospace, automotive, legaltech, insuretech, energy, process_control, building_automation — the `special_sections` named for that domain (e.g. `clinical_requirements`, `regulatory_pathway`, `compliance_matrix`, `safety_certification`, `functional_safety`, `life_safety`) must each be present and substantive, not stubbed.

What good looks like: every required special section for the detected domain present and meaningfully filled; regulatory landscape and industry terminology addressed.

What broken looks like: a high-complexity domain with two or more required special sections missing, labeled N/A without justification, or reduced to a one-line stub. A single missing section is _thin_; multiple missing on a healthcare or fintech PRD is _broken_. The fix is to expand the domain section per the `special_sections` column in `assets/domain-complexity.csv` and consult domain research for the regulatory landscape.

### 12. Project-type fit

Does the PRD cover the sections its project type requires, and skip the ones that don't apply — or has it been forced into a one-size-fits-all template?

Detect the project type from frontmatter or §1 signals and check it against `assets/project-types.csv`. Each type names its `required_sections` (e.g. `tenant_model` and `rbac_matrix` for `saas_b2b`; `endpoint_specs` and `auth_model` for `api_backend`; `platform_reqs` and `store_compliance` for `mobile_app`) and its `skip_sections` (areas that should be explicitly marked N/A rather than padded).

What good looks like: every required section for the detected type covered substantively; skip-sections marked N/A on purpose rather than filled with filler.

What broken looks like: two or more required sections missing for the detected type, or required areas reduced to a sentence. One thin required section is _thin_; multiple missing is _broken_. The fix is to expand the Project-Type section per the `required_sections` column in `assets/project-types.csv`.

### 13. Downstream usability

If this PRD feeds UX, architecture, or story creation, can those workflows source-extract from it cleanly? Traceability is the load-bearing part of this dimension and one of the unforgiving, downstream-critical ones.

Look for:

- A complete traceability chain: Vision (§1) → Success Criteria (§2) → User Journey (§4) → FR (§8), with a Traceability Matrix carrying a row per FR and no empty mapping cells. Orphan FRs — capabilities that map to no journey and no success criterion — are the headline failure.
- Glossary present; every domain noun used identically across FRs, UJs, and Success Metric definitions.
- FR / UJ / SM IDs contiguous, unique, and cross-references that resolve.
- Each section makes sense pulled out alone — cross-references via Glossary terms, not "see above."
- UJs each have a named protagonist; no floating UJs.

A missing or mostly-empty Traceability Matrix, or more than a fifth of FRs with no upstream linkage, is _broken_. For standalone PRDs (no downstream consumers), this dimension matters less — say so and mark it accordingly.

### 14. Dual-audience readiness

Can the PRD be both skimmed by a busy stakeholder and precisely extracted by a downstream tool? This is the lightest of the rigor dimensions — informational rather than gating — but worth a note when it slips.

What good looks like: each section opens with a one-to-two-sentence summary; cross-references use full IDs (`FR-AREA-NN`) rather than vague descriptors like "the auth feature above"; no forward references; lists live in real list blocks, not buried in prose.

What broken looks like: sections with no summary opener, cross-references by vague description, or forward references that force linear reading. A couple of slips is _adequate_; pervasive vague cross-referencing is _thin_. The fix is to give each section a summary opener and rewrite cross-references with full FR IDs.

### 15. Shape fit

Has the PRD been forced into a shape that doesn't match the product? This dimension governs how hard to push the others — it tells you which dimensions are load-bearing for _this_ PRD.

- Consumer product / multi-stakeholder B2B / meaningful UX → UJs with named protagonists are load-bearing.
- Internal tool, single-operator role → capability spec shape; UJs may be overhead; SMs may be operational rather than user-facing.
- Regulatory or compliance update → constraint traceability is non-negotiable; UJs may be irrelevant.
- Hobby / solo → rigor light, substance bar still applies.
- Brownfield → existing-code references must be accurate; new UJs and existing UJs must be distinguished.
- Chain-top (feeds UX → architecture → stories) → downstream usability and traceability matter more; standalone PRDs can be lighter on those.

Flag PRDs that are over-formalized (UJ density for a single-operator tool) or under-formalized (consumer product with no UJs).

## Mechanical notes

Cover these as a tail section, not a primary dimension. They matter for downstream but don't drive the verdict on whether the PRD is good.

- Glossary drift (case, plural, synonyms across the PRD).
- ID continuity (gaps, duplicates, unresolved cross-references).
- Assumptions Index roundtrip (every inline `[ASSUMPTION]` indexed; index entries all appear inline).
- UJ protagonist naming (each UJ has a named protagonist carrying context inline).
- Required sections present for the agreed stakes and product type.
- Frontmatter completeness (densityLevel / domainTier / projectType / version present; no residual `{{...}}` placeholders).