Writing requirements docs (PRDs, specs, feature docs)

You are writing or editing a document that describes what a system or feature IS — not what it was, not what changed, not who built it.

The single most common failure mode is change-narrative leaking into present-state documentation. This skill exists to prevent that. Read all of it before writing.

The core rule

A requirements doc describes present state in plain terms. Nothing else.

If a sentence answers "what changed?" or "what was it before?" or "who did this?" — it does not belong in the doc. Those facts belong in commit messages, PR descriptions, daily logs, or release notes.

The reader of a requirements doc is asking "how does this work right now / how should this work?" — not "what is the history of this feature?"

Banned phrases (catch yourself before writing these)

If you find yourself typing any of these in a PRD/spec/requirements doc, stop and rephrase as present state.

Before / after examples

Example 1: "we no longer do X"

Bad (change-narrative):

Users no longer need to verify their email before logging in. We removed the email verification step.

Good (present state):

Users can log in immediately after signup. No email verification is required.

The reader doesn't need to know it once required verification. They need to know what's true now.

Example 2: "moved" / "now lives"

Bad:

The auth service now lives in apps/api/src/auth/. It was moved from the legacy monolith.

Good:

The auth service is at apps/api/src/auth/.

Example 3: attribution + dates

Bad:

Built by Tarik on 2026-04-21. Originally added to support the NTM+ rename.

Good:

(delete entirely — attribution and origin date belong in commit history)

If the current behavior of the feature is tied to NTM+ branding, say so as present state: "Renders the NTM+ purchase confirmation page."

Example 4: change as a footnote

Bad:

The cart accepts up to 12 items.

Note: previously this was 6 items, raised in the 2026-Q1 release.

Good:

The cart accepts up to 12 items.

The footnote is change-narrative wearing a disguise. Cut it.

Example 5: "new" / "old"

Bad:

The new dashboard uses server components. The old dashboard, still served at /legacy, uses client-side rendering.

Good:

The dashboard at /app uses server components. The dashboard at /legacy uses client-side rendering.

Drop "new" and "old" — describe each one by what it is and where it lives.

Editing an existing doc: same rule applies to your additions

When updating a PRD/spec, your job is to make the doc reflect new present state — NOT to annotate what changed.

• Bad: add a "## What changed in v2" section
• Good: rewrite the affected sections so they describe the v2 present state

If the user asks you to "document what changed," push back: that belongs in the PR description, the changelog, or the commit message. The doc itself should read as if v2 has always been the way it is.

If you genuinely cannot rewrite as present state (e.g., a migration doc whose explicit purpose is to describe a transition), flag the conflict explicitly: "This deliverable conflicts with the present-state rule because the doc's purpose is migration narrative. Confirm the doc type before I proceed."

Rare valid exceptions

There are a few doc types where change-narrative IS the content:

• Changelogs (CHANGELOG.md) — entire purpose is dated change-narrative
• Migration guides — explicitly describe transitions between versions
• Postmortems / incident reports — describe what happened and when
• ADRs (Architecture Decision Records) — describe the decision in past tense + the rationale

For everything else — PRDs, specs, feature docs, READMEs, requirements docs, architecture docs, status docs — present-state only.

Other quality rules

These are secondary to the present-state rule but matter:

1. Round counts are red flags. "We have ~50 endpoints" — replace with the actual count if knowable, or omit. Round numbers in docs go stale.
2. No agent attribution. Never write "added by Claude" or "Claude generated this section." If the reader needs to know provenance, that's git blame's job.
3. No dates in prose. Dates baked into sentences rot. If a date is structurally important (deadline, deprecation window), use a labeled field: **Deadline:** 2026-06-01. Not "we need this by June 1st."
4. Single source of truth. If the same fact appears in two places in the doc, one of them is going to drift. Pick the canonical location and reference it.
5. Describe behavior, not implementation. A PRD says "the cart persists across sessions." It does not say "we use localStorage with a fallback to Redis." Implementation details belong in architecture docs or code comments.
6. Prefer concrete over hedged. "Probably should support up to 12 items" → "Supports up to 12 items." Hedging in a requirements doc creates ambiguity for implementers.

Workflow when writing a doc

1. Identify the doc type. Is it a PRD, spec, README, architecture doc, status doc? Apply the present-state rule unless it's a changelog / migration / postmortem / ADR.
2. Identify what the present state actually is. Read code, ask the user, or both. Don't write speculative present state.
3. Draft as if the feature has always been the way it is now. No history, no narrative, no attribution.
4. Self-review against the banned-phrases list. Search your draft for each banned word/phrase. Remove or rephrase.
5. If editing: same rule for your additions. Rewrite affected sections as updated present state.

Per-repo standard: 3d-game (unreal-vibes)

When writing or editing a spec in the 3d-game / unreal-vibes repo (apps/web/docs/specs/), the present-state rule above still applies, and on top of it the repo enforces an acceptance-criteria standard: apps/web/docs/process/spec-template.md.

• Every NEW spec follows that seven-section shape, and every load-bearing clause is a numbered AC-N (feature prefix, e.g. BR-* for blood, TOD-* for time-of-day). A clause with no AC-N is invisible to review.
• Implementer handoffs use apps/web/docs/process/implementer-handoff-template.md; reviewers use apps/web/docs/process/reviewer-template.md and run an AC-by-AC coverage check before scoring.

Read spec-template.md before authoring a spec in that repo.

When the user pushes back

If the user asks you to add change-narrative ("note that this is new", "add that it used to be X", "mark which section was added today"), gently push back once: "Change-history belongs in the commit/PR/changelog, not the doc itself — the doc should read as present state. Confirm if you still want it in the doc and I'll add it." Then defer to their call.