Skip to main content

SC PRD Standard

Purpose​

Defines what a well-formed PRD looks like in docs/prds/, and reconciles the competing PRD authorities available to this repository into one operative rule set.

This standard is the human-readable companion to scripts/validate-prd.py: every check the validator enforces has a section here explaining what it checks, why it matters, and how to fix a violation. The validator's failure strings deep-link into this doc by section anchor.

A PRD exists to describe a need and the benefit of meeting it. It is not a design document, an implementation plan, or a record of how the situation arose.

Scope​

Applies to every file in docs/prds/.

Does not apply to:

  • Legacy PRD-*.md files under docs/projects/ and its category subfolders. Those remain governed by PRD Template and PRD Guide.
  • The frozen snapshot in docs/prd-library/, which is status: reference and exempt from the frontmatter standard by its own README.
  • SOPs, runbooks, standards, and process documentation. Those have their own templates. A PRD is not the right container for an operational procedure.

Which authority governs​

Four bodies of guidance describe PRDs. They disagree. For docs/prds/, precedence runs:

RankAuthorityGoverns
1This standardEverything in docs/prds/. Where it is silent, rank 2 applies
2The prd-creator skill and its templatesSection structure, tier calibration, requirement ID scheme, the litmus test
3saas-requirements-writing-guide.md in the reference-docs repositoryThe underlying method: Problem Over Solution, user stories, Given-When-Then acceptance criteria, document sizing
4SC Markdown Standard and SC Tagging StandardEverything not covered above, subject to the carve-out below

Carve-out from the SC Markdown Standard. Its Prohibited Practices list forbids markdown tables, checkbox symbols, square-bracket placeholders, and dates in file names. All four are permitted inside docs/prds/, because the requirement, traceability, and metrics structures this standard mandates are inherently tabular, and the directory's established naming convention is date-prefixed. The carve-out is named in the Markdown Standard itself so the two do not silently conflict. It extends no further than this directory.

Category and status. docs/prds/ files use type: product-prd or type: process-prd rather than the Markdown Standard's category enum, and draw status from the set below.

Validator rule index​

The eleven checks below are enforced by python scripts/validate-prd.py. Each check name maps to a section anchor in this doc.

CheckSection anchorSeverity
filename#filename-ruleBlocking
frontmatter#frontmatter-ruleBlocking
scope_tier#scope-tier-ruleBlocking
sections#sections-ruleBlocking
requirement_ids#requirement-ids-ruleBlocking
traceability#traceability-ruleBlocking
success_metrics#success-metrics-ruleBlocking
problem_validated#problem-validated-ruleBlocking
named_individuals#named-individuals-ruleBlocking
historical_commentary#historical-commentary-ruleAdvisory
length_budget#length-budget-ruleAdvisory

Anchor convention: check name to kebab-case plus a -rule suffix. scope_tier becomes #scope-tier-rule.

Blocking checks set exit code 1 when the file is part of the change under review. Advisory checks surface as warnings and never fail a build.

Frozen records are exempt. A PRD with status: deprecated or status: archived is skipped. Holding a superseded document to the current standard would demand edits to a document whose purpose is to stay as it was.

Two modes. validate-prd.py --changed inspects only PRDs modified in the current diff and fails on any Blocking violation. A bare invocation reports across the whole directory without failing, so PRDs written before this standard surface as a backlog rather than a wall.

The governing principle​

Every requirement describes what someone needs and why, never how to build it.

Litmus test: can a reader propose more than one valid way to satisfy this requirement? If yes, it is written correctly. If the wording admits exactly one implementation, it is solution-prescriptive and belongs in an appendix or an implementation note, not in the requirements table.

Solution-prescriptiveNeed-based
Add a branch protection ruleset requiring one approving reviewChanges reach the canonical branch only after review by a designated owner
Store the seat list in a config standardEvery access holder's entitlement is recorded where an auditor can find it
Send a Slack notification on failureNotify the responsible party when the process fails
Create a cron job to run daily at midnightExecute the process on a recurring daily schedule

Permitted specificity. Detail that comes from the problem domain or an external constraint stays. "Must work with the existing GHL sub-account", "must meet WCAG 2.1 AA", "invitations go to personal email under existing contractor policy" are constraints, not implementation preferences. Detail that comes from a preference is removed.

Tier calibration​

Every PRD declares a tier, and the tier determines which sections are required. Declaring Tier 1 for a small change produces a document nobody reads.

TierScopeBudgetRequired sections
1New product, system, or service5-15 pagesAll sections in the list below
2Major capability added to something that exists2-5 pagesExecutive Summary, Goals and Desired Outcomes, Context, Problem Validation, MVP Definition, Requirements, Success Metrics, Open Questions, Revision History
3Enhancement, configuration change, small additionUnder 2 pagesExecutive Summary, Problem Validation, Requirements, Success Metrics, Revision History

Sections available at Tier 1: Document Control, Executive Summary, Goals and Desired Outcomes, Context, User Personas, Jobs-To-Be-Done, Problem Validation, Opportunity Solution Tree, MVP Definition, Requirements, User Stories, Success Metrics, Timeline and Milestones, Dependencies, Constraints, Risks and Mitigations, Related Documents, Glossary, Open Questions, Appendix.

Root Cause Analysis is required at every tier, inside Problem Validation. A five-line table is not a burden and it is the section that most often changes what the PRD asks for.

Rules​

filename-rule​

Files match YYYY-MM-<kebab-description>-prd.md. Lowercase, hyphens only, no version number in the name — the version frontmatter field carries that.

frontmatter-rule​

Required keys, with allowed values:

  • title — prefixed PRD: or PRD -
  • version — starts at 1.0; the major number increments on a structural rewrite
  • type — product-prd or process-prd
  • status — draft, review, active, completed, archived, or deprecated. completed is a PRD-only state meaning the work the PRD authorised has shipped
  • author
  • created and last_updated — YYYY-MM-DD
  • tags — includes prd. The SC Tagging Standard recommends 2 to 6; the validator treats the count as advisory
  • scope_tier — 1, 2, or 3
  • problem_validated — boolean
  • category — lowercase, hyphenated; product-requirements for PRDs in this directory. Not checked by validate-prd.py, but required by the repo-wide gate validate-docs.py, which runs on every changed markdown file. A PRD missing it passes the PRD check and still fails CI

Recommended: reviewers, next_review, related_documents, priority, estimated_effort, target_release, routing.

Read the whole frontmatter block before editing any of it, per yaml-frontmatter-edits. Duplicate keys are silent corruption.

scope-tier-rule​

scope_tier is present and is 1, 2, or 3. It is not optional and there is no default — the tier is a judgement about the size of the work, and refusing to make it is how a one-page change becomes a fifteen-page document.

sections-rule​

Every section required by the declared tier is present as an H2, spelled as written in the tier table. A required section may not be empty.

requirement-ids-rule​

Three families, three-digit zero-padded, unique within the document, never reused even when a requirement is dropped:

  • OR-NNN — outcome requirements. What the reader gets. The why.
  • FR-NNN — functional requirements. What must be true. The what.
  • NFR-NNN — non-functional requirements. Quality attributes and constraints.

Cross-document references take the form <prd-slug>-FR-001.

An ID is defined where it opens a row in a requirements table. The Traceability subsection re-opens rows keyed by outcome ID by design, so it does not count as redefinition.

Table shapes:

| ID | Desired Outcome | How We Measure Success | Priority | Status | | ID | Requirement | Enables Outcome | Priority | Status | | ID | Category | Requirement | Target | Enables Outcome | Status |

Outcomes are not features. "The system has a dashboard" is a feature wearing an outcome's clothes. Ask "so what?" until the answer is a benefit somebody receives.

traceability-rule​

Every FR and NFR names at least one OR in its Enables Outcome column, and every OR referenced exists. The PRD carries a Traceability subsection listing outcomes against the requirements that serve them, and states explicitly whether any requirement is orphaned.

An orphaned requirement is a requirement nobody asked for. Delete it or find the outcome it serves.

success-metrics-rule​

A Success Metrics section is present with at least one measurable statement. Tier 1 and 2 separate leading indicators from lagging indicators; Tier 1 also names a single north star.

A PRD with no success metric cannot be evaluated after the fact, which means the work it authorises can never be shown to have mattered.

problem-validated-rule​

problem_validated: true requires evidence in the Problem Validation section: a quantified measurement, a recorded stakeholder statement, or an impact figure.

Not evidence: sole-author observation, unquantified intuition, "a competitor does this", or "leadership asked for it".

Where evidence is genuinely unavailable, set problem_validated: false and carry a LOW CONFIDENCE banner immediately under the title. The banner stays until evidence lands.

named-individuals-rule​

Body text names roles, never living individuals, per reference-roles-strictly. Revision History rows and the author and reviewers frontmatter fields are exempt, as historical records.

historical-commentary-rule​

Body text describes the current state. What changed and when belongs in Revision History, per historical-commentary-belongs-in-changelog.

A PRD is especially prone to this, because the reasoning that produced it feels like context. It is not. If a fact about the past is load-bearing for a decision today, state the resulting constraint in the present tense and put the history in a Revision History row.

Advisory rather than Blocking, because the phrasings that signal it also occur legitimately — a Context section may describe a current baseline in terms of what it replaced.

length-budget-rule​

The document stays within its tier's budget, counted at roughly 400 words to the page. Tier 3 is budgeted at two pages rather than the one its upstream sizing table suggests, because outcome-traced requirements and a root-cause table are required at every tier and do not fit in a page. Exceeding it usually means the tier is wrong, not that the budget is.

Authoring​

Invoke the prd-creator skill. It carries the templates, the tier logic, and the litmus test, and it produces the section skeleton this standard requires. Do not hand-author the structure from memory — that is the failure this standard exists to prevent.

Then run python scripts/validate-prd.py --changed before opening the pull request. Continuous integration runs the same check, so a violation found locally costs a minute and a violation found in CI costs a round trip.

Revision History​

DateVersionChange DescriptionAuthor
2026-08-201.0Initial standard. Reconciles the four PRD authorities into one precedence order for docs/prds/, names the carve-out from the Markdown Standard's table and filename prohibitions, and pairs each rule to a check in scripts/validate-prd.py following the pre-work standard's linter-index pattern.Symphony Core Systems Team
2026-08-311.1Added category to the required frontmatter keys. It is not checked by validate-prd.py but is required by the repo-wide gate validate-docs.py, so a PRD could pass the PRD check with zero findings and still fail CI — which is exactly what happened to 2026-08-engineering-portfolio-refresh-prd.md. Only 4 of the 26 PRDs then in docs/prds/ carried the key, so the trap was general rather than incidental.Symphony Core Systems Team