prd-quality-rubric

name	prd-quality-rubric
description	Critic scoring rubric for drafted specs. Defines dimensions D1–D4 (both modes) and D5–D8 (update mode only), per-dimension scoring guidance, weighted aggregation, verdict thresholds (pass/revise/block). Replaces literal-diff-based rubric. Triggers on: score the spec, critic rubric, D1 mandatory coverage, D2 gated appropriateness, verdict thresholds.

PRD Quality Rubric

This skill is the source of truth for @prd-critic's scoring. It defines the dimensions, scoring guidance per dimension, weighted aggregation, and verdict rules.

When to Use This Skill

Load this skill when:

• Scoring a drafted spec (@prd-critic).
• Authoring or maintaining the eval spec.yaml rubric list (the rubric IDs in the eval spec mirror the dimension IDs here).

Domain neutrality

Dimensions are domain-neutral. The critic does NOT penalise the absence of an industry-specific section the user did not request, and does NOT reward the presence of one. User-approved Stop A overrides for section names are honoured at face value (D3).

Dimensions

D1 — mandatory-coverage (both modes)

Question: Are all mandatory sections from the prd-template catalogue present and non-empty (or marked [TBD] with a corresponding OQ-NN entry in "Open Questions")?

Scoring: count present / total mandatory; partial credit for [TBD] entries that have a matching OQ entry.

Common deductions: missing "Open Questions" section entirely; mandatory section present but empty without [TBD].

D2 — gated-appropriateness (both modes)

Question: For each complexity-gated section, is the include/omit decision justified by the §heuristic given the inputs AND the user-chosen spec_kind (see prd-template)?

Scoring:

• Penalise bloat: gated section present without a triggering axis being detectable in the inputs, OR without spec_kind permitting it.
• Penalise underspecification: axis present in the inputs AND spec_kind permits inclusion, but the section is omitted.
• Reward correctly omitted sections with a clear rationale in section-decisions-json (including gated-omitted-by-spec-kind).
• In spec_kind: product, do NOT penalise omission of implementation-shaped sections (Data Model, API Contract, Capacity & Performance Targets, Threat Model Summary, Versioning & Deprecation Policy, NFR↔FR Traceability) regardless of axis.
• experience-surface axis (the UX section). The gated "User Experience: Personas, Journeys & Roles" section is scored like any other gated section: reward correct omission when the axis did not fire (non-UI-forward spec, or a single-affordance tweak caught by the non-fire guardrail); penalise bloat when the section is present without a UI-forward signal; penalise underspecification when the axis clearly fired (new screens/flows/nav, or role-varying UI behaviour) but the section is missing. Do NOT penalise a non-UI-forward spec for lacking the section — the concepts belong woven per spec-driven-prd-best-practices §11 instead (scored under D4/D11, not D1/D2).

D3 — naming-consistency (both modes)

Question: Do section names match the neutral catalogue, OR a Stop-A-approved override?

Scoring: any drift from the catalogue without an override deducts. Industry-specific labels without explicit Stop A approval deduct heavily.

D4 — content-quality (both modes)

Question: Is the prose clear; are FRs in EARS shape; are acceptance criteria testable and nested under their FR; do NFRs (when present) trace to FRs; is there fabrication; is evidence discipline upheld; is format hygiene upheld?

Scoring: penalise:

• Non-EARS FR statements (multiple shalls, missing <system> shall, intention-shaped triggers, passive-voice responses). See spec-driven-prd-best-practices §4a.
• Non-testable acceptance criteria; ACs not nested under their FR; ACs without AC-<FR>.<n> IDs.
• Untraceable claims (no footnote and not derivable from the context pack).
• Vague goals without baseline + target + measurement window.
• Missing P0/P1/P2 priority on FRs.
• Evidence-discipline violations. Apply the following severity schedule (overrides the default-to-minor rule):
  • blocker — any footnote whose URL resolves to a gitignored / session-local / local-scratch path (per spec-driven-prd-best-practices §8 and .gitignore). Verdict goes to block regardless of weighted score. The drafter is required to remove the footnote (not relabel it, not move it to a "References" appendix).
  • blocker — any footnote pointing at a non-authoritative or non-primary source (e.g. a third-party blog post quoting the standard instead of the standard itself). The drafter must replace it with the primary source or drop it.
  • major — a footnote that adds no value (decorative or redundant; a competent reader could act on the section without it). The drafter must drop it; verdict revises.
  • major — S1, S2 numeric scheme; "Citations" appendix table present.
  • minor — formatting issues (bare section reference instead of an anchored link, missing URL on a footnote that is otherwise valid).
• Format-hygiene violations: hard-wrapped body paragraphs; bold-as-header; structure carried by bolded lines instead of ###/#### headers.
• Upper-section isolation violations (per prd-template §"Per-section isolation contract"):
  • Solution Summary restates problem narrative, or names owners / metrics / FRs / rollout detail → major per offending section.
  • Goals restates the problem, or names owners, or describes solution mechanics → major per offending section.
  • Problem Statement preempts the solution ("we will add…"), or names owners, or pre-states goals → major per offending section.
  • Ownership / stakeholder content surfacing in any non-Ownership upper section → major.
  • Repeat offence across three or more upper sections → escalate one finding to blocker.

User-context weaving (non-blocking quality guidance). When user-context concepts are present, reward good craft but do NOT treat their absence as a mandatory-coverage (D1) miss — these are woven-context quality signals, not required sections:

• Personas that carry a JTBD job statement in the "When … I want to … so I can …" form (minor credit; a persona with a vague need is a minor deduction, not a blocker).
• Journey steps that decompose into event-driven FRs/ACs rather than sitting as narrative only.
• Role-conditioned behaviour expressed as EARS optional-feature FRs (Where <role> is included, the <system> shall …) with an AC pinning the deny path.

Absence of a JTBD column, journey mapping, or role matrix on a non-UI-forward spec is NOT a deduction (constraint: no new blanket-mandatory section). Strict scoring of these on UI-forward specs lives in D11.

D9 — scope-discipline (both modes when spec_kind is product or mixed; null otherwise)

Question: In product / mixed mode, is implementation content kept out of FRs and confined to a "Technical Considerations" appendix (mixed) or omitted entirely (product)?

Scoring: penalise:

• Any FR that names an internal component, library, datastore, framework, language, or specific API in product / mixed mode.
• Inline implementation content next to FRs in mixed mode (it belongs in "Technical Considerations").
• Boilerplate "implementation is out of scope" / "technical design choices are out of scope" entries in Out of Scope.

In spec_kind: technical, D9 is reported as null (not 0) — the dimension does not apply.

D5 — changelog-completeness (publish-transition turns only)

Question: When the spec transitioned Status: draft → published this turn (V8 — version-bump-json.kind ∈ {publish-initial, publish-redraft}), does CHANGELOG.md exist, use the Keep-a-Changelog categories, and account for every change visible between prior and revised?

Scope: D5 applies only on publish-transition turns. On any turn where Status: draft at end-of-turn (initial draft OR re-draft window edit without publish intent), D5 is reported as null, not 0 — drafts produce no CHANGELOG (V3 / V17 / OQ-5).

Scoring: any diff that does not appear in at least one category deducts. Wrong category placement is a minor deduction.

D6 — id-stability (update mode only)

Question: Do all prior requirement IDs (FR-, NFR-, AC-, R-, OQ-, TS-) still resolve in the revised spec?

Scoring: silent deletion of an ID is a blocker finding. Renumbering is a blocker finding.

Sub-rubric d6.removal-by-status (severity: blocker; defined by prd-evolution §3 + versioning-discipline §V9):

• In Status: draft (initial OR re-draft window — applies to any item removed regardless of whether it was newly added in-window or carried over from a prior published version): a removed item that left a [Deprecated] / [Removed] stub heading, or any prose narrating the removal ("formerly FR-07…", "removed in this revision…"), in the draft body is a blocker finding. Drafts delete cleanly per prd-evolution §3a / §3b (interpretation (a)).
• In Status: draft (any flavour): a removed in-window FR/NFR/R/ OQ/TS that did NOT trigger renumbering of successors (leaving a numbering gap) is a blocker finding. Prior-published IDs are NOT renumbered (V9 over the ID is permanent) — gaps in the prior-published number space are expected and not a finding.
• In Status: draft (re-draft window): a removed prior-published ID for which state.json:pending_published_id_deletions does NOT contain a matching entry is a blocker finding. The drafter must queue the deletion for publish-time re-materialisation; silent drops break V9 at the next publish.
• In Status: published end-of-turn (publish-transition turns only): a deleted prior-published item with no [Deprecated] / [Removed] stub heading in the published artefact is a blocker finding (V9 published-contract violation). At publish, every entry that was in pending_published_id_deletions MUST have been re-materialised in the published artefact body (V8 step 4a).
• In Status: published end-of-turn: a renumbered prior-published item is a blocker finding (V9 numbering immutability).

D7 — versioning-correctness (update mode only)

Question: Does the version bump match the prd-evolution rule (MAJOR/MINOR/PATCH)? Is the Updates: / Obsoletes: header present?

Scoring: wrong bump or missing header is a major finding.

Sub-rubric d7.draft-no-change-tracking (severity: blocker; defined by prd-evolution §5):

Applies in any turn where the spec ends Status: draft (initial draft OR re-draft window with no publish intent). The drafted spec body MUST NOT contain ANY of:

• A ## Changes since heading (any version suffix or "since vN" variant).
• A ## Revision History, ## Changelog, or ## What's Changed heading.
• An inline [Changed in v...] marker (anywhere — heading, list item, or paragraph).
• An HTML / markdown comment narrating what changed (<!-- changed: ... -->, <!-- added in v... -->).
• Prose narration of revision history ("Added in this revision", "Removed since v1.0", inline parenthetical "(updated)" tags).
• A CHANGELOG.md mutation this turn (overlap with d7.publish-changelog — re-stated here so the rubric is self-contained when the critic runs against a draft turn).

Any single occurrence is a blocker finding. The verdict escalates to block regardless of weighted score. The fix is to delete the offending construct (not move it, not rename it).

D8 — section-stability (update mode only)

Question: No silent renumbering. No removed gated section without a changelog rationale.

Scoring: silently removed gated sections deduct heavily.

D10 — edit-minimalism (update mode only)

Question: Did the drafter make the smallest set of edits that fully reflects (a) the user's stated feedback, (b) any Stop-A-approved missing context, and (c) the ID-stability mechanics those edits trigger — and NOTHING else?

Inputs: the drafter's edit-audit-json; a structural diff between prior_spec_path and spec_path (use the read tool to load both files and compute a section-by-section diff in working memory; you do not need an external diff tool).

Scoring (start at 1.0; deduct):

• For each modified or reordered span present in the diff but NOT listed in edit-audit-json: deduct 0.2 and emit a major finding. An edit the drafter cannot account for is by definition unjustified.
• For each edit whose recorded reason does not survive scrutiny — e.g. reason: requested but the user request never mentioned that section, or reason: correctness for a span that was not factually wrong — deduct 0.2 and emit a major finding.
• For each edit that is purely stylistic (prose reword with no semantic change), reordering with no requested driver, or template drift (renaming a section to match a newer skill default the user did not ask for): deduct 0.3 and emit a major finding. If three or more such edits are present, escalate ONE finding to blocker.
• If the drafter omitted edit-audit-json entirely in update mode: emit a single blocker finding and score D10 = 0.
• Upper-section edit ratchet. Any modified or reordered span whose location is in Document Information (excluding version mechanics), Problem Statement, Goals & Success Metrics, Users & Personas, Stakeholders & Reviewers, or Solution Summary carries a 2× weight against D10. An upper-section edit whose justification does not quote / directly paraphrase a user request: deduct 0.4 (not 0.2) and emit a major finding. Two or more such edits in one turn: escalate ONE finding to blocker. Rationale: the user explicitly named upper-section stability as a hard discipline; D10's standard schedule under-weights it.
• Per-statement scoring. D10 evaluates sentence-level diffs, not span-level diffs. For each sentence that differs between prior_spec_path and spec_path:
  • If listed as a sentence-level entry in edit-audit-json with a surviving reason → no deduction.
  • If not listed, OR listed only at paragraph/section granularity → deduct 0.2 and emit major.
  • If the only difference is whitespace, punctuation, capitalisation, grammar, or stylistic word-substitution (i.e. the kind of change §0's per-statement gate routes to REVERT) → deduct 0.3 and emit major. Three or more such sentences → escalate ONE finding to blocker.
• Default disposition in findings. D10 findings whose recommended fix would normally be "drop / re-justify the edit" MUST instead read "revert the sentence to the prior wording at <prior_spec_path>:<line>". The fix wording matters: it tells the next drafter pass that REVERT — not re-edit — is the required remediation.

Common deductions: rewording the Problem Statement when the user asked only to change one FR; reordering Goals; renaming a section that the alias appendix does not record; tightening NFR prose; switching table layouts; "normalising" capitalisation across the document.

Out of scope for D10: ADD-only edits that the user requested (e.g. "add an FR for X") — those are the legitimate change. D10 polices edits to the prior content, not new content.

D11 — user-context-grounding (scored ONLY when experience-surface fired; null otherwise)

Question: For a UI-forward spec (the experience-surface axis fired and the "User Experience: Personas, Journeys & Roles" section is present), is the user-context treatment concrete and grounded?

Applicability: D11 is scored only when experience-surface fired for this spec. On every other spec (non-UI-forward, or the non-fire guardrail applied) D11 is reported as null, not 0 — same null-not-zero convention as D5–D8/D10. This localises the strictness to UI-forward specs and keeps it out of every other spec's score, honouring the "no new blanket-mandatory section" constraint.

Scoring (start at 1.0; deduct):

• Personas in the dedicated section lack a concrete JTBD job statement (the "When … I want to … so I can …" form): deduct 0.2 per persona, minor.
• At least one user journey for the primary affected flow is missing or is narrative-only (no phase/step table, no mapping to FRs): deduct 0.3, major.
• Role-varying behaviour is described but no Roles × Permissions matrix (or equivalent role→capability mapping) is present: deduct 0.3, major. If the matrix omits the deny-by-default posture or no AC pins a deny path, deduct a further 0.2, minor.
• User-context content is fabricated (invented persona/job/journey/ role with no basis in the context pack, interview answers, or a cited source, and not marked [TBD]/OQ-NN): this is a fabrication finding — blocker (verdict block), consistent with D4's fabrication rule.

Reward: concrete, source-grounded personas + JTBD + at least one FR-decomposed journey + a deny-by-default role matrix → 1.0.

Weighted aggregation

Equal-weight mean of applicable dimensions only. Dimensions not applicable in the current mode are reported as null, not 0, in scores-json. D10 follows the same null-not-zero rule as D5–D8: it is included in the weighted mean only when mode == update.

weighted = mean(dim for dim in [D1..D11] if dim is not null)

Verdict rules

• block — any blocker finding (e.g. silent ID deletion, fabricated facts, mandatory section missing AND no OQ entry).
• revise — weighted < 0.7 OR any major finding.
• pass — otherwise.

Severity guidance

Severity	When to use
blocker	The spec must not ship as-is. Examples: silent ID deletion in update mode; mandatory section missing without OQ; fabricated facts; any footnote citing a gitignored / non-authoritative / non-primary source (per spec-driven-prd-best-practices §8).
major	Significant quality issue that should block this draft. Examples: NFR section present without any traceable axis; non-testable AC across most requirements; wrong version bump kind.
minor	Polish issue. Examples: a single non-testable AC; missing citation on one claim; naming drift on one heading.

Threshold tuning

The 0.7 threshold for revise is tunable. Consumers who want to lower the bar for first drafts can raise it; consumers in high-trust pipelines can lower it. Adjust here, not in the .agent.md of @prd-critic.

Quality checklist (for the critic itself)

• Every applicable dimension scored in [0, 1].
• Inapplicable dimensions reported as null.
• weighted matches the formula above.
• Verdict matches the rules above.
• Findings sorted by severity (blocker > major > minor).
• Every finding has dimension, severity, issue, fix.