| name | prd-reviewer |
| description | Review an existing PRD for completeness, accuracy, and staleness. Use when the user asks to "review a PRD", "check if a PRD is up to date", "validate a PRD", or when opening a PR that touches a package covered by a PRD. Checks that the PRD accurately reflects the current implementation, that acceptance criteria are testable, that spec alignment is correct, and that rationale sections contain real context rather than code paraphrase. |
PRD Reviewer
You are reviewing a Product Requirements Document (PRD) for the PIE-QTI framework. Your job is to find problems that matter — not style nits.
What you're checking for
1. Accuracy against current implementation
Read the source for the package(s) listed in the PRD. Compare against what the PRD claims.
Check:
- Do the listed supported/omitted attributes match what the code actually handles?
- Do the acceptance criteria match the real behavior (not an idealized version)?
- Are extension points documented at the right level of abstraction — i.e., do they reflect the actual interface contracts in the code?
- Are any design decisions documented that have since been reversed or changed?
Flag as [STALE] anything that no longer matches the code.
2. Spec alignment correctness
For interaction and architecture PRDs, verify QTI spec claims using the qti-domain-expert skill when needed.
Check:
- Are supported/omitted attributes listed accurately against QTI 2.2 (and 3.0 if applicable)?
- Are any documented divergences from spec actually divergences, or are they correct spec-compliant behavior?
- Are variable names (baseType, cardinality, response identifiers) correct?
Flag as [SPEC-ERROR] anything that misrepresents the QTI spec.
3. Acceptance criteria quality
Each AC should be self-contained and unambiguously testable. Apply this bar: could a QA engineer who has never seen this codebase verify the criterion using only the PRD and the demo app?
Reject criteria that:
- Reference internal state not visible through the UI or browser DevTools
- Describe implementation rather than observable behavior ("the component calls X method" is not an AC)
- Are too vague to have a clear pass/fail ("the interaction feels responsive" fails the bar)
- Are missing important edge cases that are called out in the Background section or known from the spec
Flag as [WEAK-AC] with a suggested rewrite.
4. Rationale completeness
The Background and Design Decisions sections should contain real constraints, not code paraphrase. "We used a registry because it's extensible" is not rationale. "We used a priority-based registry because vendor-supplied components must be able to override default components for specific interaction types without modifying framework code" is rationale.
Flag as [THIN-RATIONALE] when a section just restates what the code does without explaining why.
5. Missing coverage
Check whether the PRD covers the full scope of what its title implies.
For interaction PRDs: Are all QTI attributes (at minimum the ones in the spec's normative table) addressed? Are accessibility requirements for this specific interaction type present?
For architecture PRDs: Are all public extension points documented? Are cross-subsystem contracts (what this package expects from its callers, what it guarantees to its consumers) covered?
For system PRDs: Are all packages that participate in this cross-cutting concern mentioned?
Flag as [MISSING] with a description of what's absent.
6. Open questions hygiene
Open questions that have been resolved in the code but not removed from the PRD should be flagged as [STALE-QUESTION].
Output format
Report findings grouped by severity:
Critical — PRD is misleading or incorrect (STALE, SPEC-ERROR): must fix before merging.
Important — PRD is incomplete in a way that matters (MISSING, WEAK-AC): should fix before merging.
Minor — PRD could be better (THIN-RATIONALE, STALE-QUESTION): fix when convenient.
For each finding:
[SEVERITY] [TAG] Section: "..."
Issue: what's wrong
Fix: what to write instead (or what information to gather)
If the PRD passes review, say so explicitly and update its status in docs/prds/INVENTORY.md to current (or keep needs-update if you found issues).
When to invoke this skill proactively
- When opening a PR that touches
packages/<name> — check if a PRD exists for that package and flag if it needs updating.
- When a PR changes a public interface (type, registry, component API) — check the corresponding architecture PRD.
- When the user asks to write or update an AC or test — first check whether a PRD exists that should be the source of truth.
Skills to use proactively
- qti-domain-expert — to verify spec claims in the QTI alignment section
- pie-domain-expert — when reviewing transform or PIE↔QTI boundary PRDs
- accessibility-reviewer-assessments — to validate completeness of accessibility AC sections
- api-design-reviewer — when the PRD covers a public extension API
