Skip to content

DEV-180.md

Latest commit

 

History

History
37 lines (30 loc) · 1.39 KB

DEV-180.md

File metadata and controls

37 lines (30 loc) · 1.39 KB
Raw
id DEV-180
title Keep the Spec as Unimplemented Behavior and Graduate It
status active
enforcement manual
severity error
depends_on
DEV-110
DEV-170

Problem

When a Spec describes behavior that already shipped, or docs/product/ describes behavior that was never built, a reader cannot tell what the product actually does today. The backlog and the documentation rot into fiction.

Solution

Split intended behavior from shipped behavior, and move sections across as work lands.

  1. docs/specs/<feature>.md holds only unimplemented behavior for a Goal. docs/product/<feature>.md holds only what currently ships.
  2. Each PR that delivers behavior moves the corresponding sections out of the spec and into the appropriate file under docs/product/. A spec may graduate into more than one docs/product/ file.
  3. When scope is added after the Spec merges, open a new PR against the spec file and create Problem issues for the added scope.
  4. When every section has graduated, keep the spec file as frontmatter only. Never delete it, so the Goal's # Spec link keeps working.

Acceptance Criteria

  • docs/specs/ holds only unimplemented behavior
  • docs/product/ holds only shipped behavior
  • Each shipping PR graduates the delivered sections from spec to docs/product/
  • A fully graduated spec file is kept as frontmatter only, not deleted