Reference — generated from the toolkit

Source of truth: toolkit/skills/pfd-review/spec.md. Edit it there; this page is regenerated on build.

Skill: pfd-review

• Owner: Product + Test (with AI)
• Version: 0.1.0
• Lifecycle: draft
• Phase: definition

Trigger

Run on every PFD draft before the Definition of Ready gate is requested, and on any PR that changes a PFD. It is the automated half of the gate's ambiguity and completeness checks — humans review exceptions, not basics.

Inputs → outputs

• Inputs: the PFD draft (from the PFD template), the product's glossary, the domain brief, and the PFD quality rubric.
• Outputs: a completed draft of the rubric's Scores table (evidence-anchored, section/line per finding), plus a findings list: banned-word hits, untestable ACs, rules missing examples, orphan terms, missing/target-less NFR, compliance or commercial sections, and untriaged open questions.

Procedure

1. Ambiguity lint — flag every banned vague word per the acceptance-criteria standard (appropriate, quickly, fast, robust, user-friendly, etc., and so on, handle gracefully), with location.
2. AC testability — check every AC is Given/When/Then with concrete values a test agent could execute without interpretation; flag any that a test cannot check.
3. Rule exemplification — for each rule, verify a positive, a negative and a boundary worked example exist; flag the gaps by rule.
4. Glossary cross-check — every domain term used in the PFD resolves in the glossary; list orphan terms and terms used inconsistently with their glossary definition.
5. Section completeness — NFR rows carry testable targets (per the NFR catalogue), compliance constraints are stated, the commercial section is present and non-placeholder.
6. Open-question hygiene — every open question is triaged blocking/non-blocking with an owner; flag blocking questions and prose-buried "we may need to…" questions.
7. Draft rubric scores — fill the Scores table with evidence pointers and state whether the gate threshold (no dimension below 3, average ≥ 4) is met.

Guardrails & permissions

• Read-only on the PFD, glossary and brief; it reports, it never edits — least privilege per the guardrail standard.
• Scores are drafts. The PO and reviewers confirm or adjust them; the skill's output alone never passes the gate.
• Form, not truth. It checks that rules are well-expressed, not that they are domain-correct — SME sign-off is a separate, unwaivable gate criterion.

Failure modes

• False positives on banned words inside quoted client language (mitigated: words inside quotation marks are reported separately, not counted against the score).
• A well-formed but domain-wrong rule sails through (mitigated by design: the gate still requires recorded SME sign-off).
• Orphan-term misses on inflected or compound forms ("endorsements", "MTA'd") (mitigated: match on lemmas; residual misses caught at SME review).
• Rubric-score drift between runs (mitigated: evidence required per score; golden scenarios pin expected scores).

Golden scenarios

Scenario	Input	Expected output	Pass criterion
Seeded-defect PFD	fixture PFD with 10 seeded violations (banned words, missing boundary example, orphan term, target-less NFR)	≥ 9 of 10 flagged with correct locations	recall ≥ 0.9, no fabricated findings
Clean PFD	gold-standard fixture PFD	average rubric score ≥ 4, no dimension below 3, zero false findings	precision on clean fixture
Quoted client language	PFD quoting a client saying "quickly"	hit reported as quoted, excluded from score	correct classification
Rule missing negative case	fixture rule with positive + boundary only	that rule flagged under exemplification, others untouched	exact-match on seeded gap