---
name: feedback-prd-writing
description: Style rules and anti-patterns for writing PRDs — every acceptance criterion must name its verification artifact; paired good/bad examples for the common drift modes.
metadata: 
  node_type: memory
  type: feedback
  originSessionId: 5fcd9911-2376-443b-a4e0-26bc1a83ce7e
---

PRD writing rules for any project under Jared's setup. These apply during
`/new-prd`, `/audit-prd`, and any time Claude writes, reviews, or edits a PRD.

**The single rule that catches the most drift:** every acceptance criterion
must name the artifact that proves it — a test file path, a manual QA step,
or a metric+threshold. If you can't name the artifact, the criterion isn't
done — it's a wish.

**Why:** vague acceptance criteria are the leading cause of scope drift and
"is this done?" arguments at the end of an implementation. Naming the
verification artifact during PRD-writing surfaces ambiguity *before* code
starts, when fixing it is cheap.

**How to apply:** during PRD creation or audit, reject any AC that doesn't
name its verification. Push back on "should work correctly" / "should be fast"
/ "is robust" — these are not testable. The rule is the same whether the
verification is automated or manual; the point is that the artifact exists
and is named.

---

## Paired examples — acceptance criteria

| ✗ Vague | ✓ Testable |
|---|---|
| The API should be fast | p95 latency for `GET /v1/users` is below 200ms under 100 RPS sustained for 1 hour (verified by `tests/load/users_latency.test.ts`) |
| Login should be secure | Failed login attempts above 5 within 60 seconds from a single IP return HTTP 429 (verified by `tests/integration/rate_limit_test.php::test_login_429`) |
| Users can export their data | Given a logged-in user, when they click "Export" on Settings, they receive a `.zip` containing `profile.json`, `posts.csv`, and `media/` within 60 seconds (verified by `ExportTest::test_full_export` and QA step in `docs/qa/export.md`) |
| The page should look good | Page passes WCAG 2.1 AA contrast check; matches Figma frame `dashboard-v3#42`; verified by Miss Piggy review and `axe` automated scan in CI |

## Paired examples — success criteria

| ✗ Vanity | ✓ Measurable |
|---|---|
| More users will use the feature | Active users of `/export` ≥ 5% of weekly actives within 30 days post-launch |
| Customers will be happier | Support tickets tagged `export-broken` drop by ≥ 50% over the 60 days following rollout |
| The system will be more reliable | Uptime for `/export` ≥ 99.5% measured monthly, with no incident requiring rollback in the first 90 days |

## Anti-patterns — reject these in PRDs

- **"Should be …"** without a number. Performance, security, scalability all
  need targets, not adjectives.
- **"User-friendly" / "intuitive" / "delightful"** without a usability test
  protocol or metric (task completion time, error rate, SUS score).
- **"Robust"** — define which failures are tolerated and which aren't.
- **"Scalable"** without a target capacity (RPS, GB, concurrent users).
- **Acceptance criteria written as feature lists** ("supports CSV export,
  supports JSON export") rather than testable outcomes ("CSV export
  round-trips through `parse_csv()` with no data loss for the standard
  fixture set").
- **Empty Out of scope** — almost always means scope hasn't been bounded.
  Force at least one explicit non-goal.
- **Unowned open questions** — every open question has a named owner, or it
  blocks Walter.

## When to relax

For a 30-minute exploratory spike, a 5-line PRD with one acceptance criterion
is fine: "done when I've prototyped X and can answer: do we go ahead with
this approach? Y/N." The rules above are for work that will actually ship.

Linked: [[user-role]] [[feedback-style]].