spec-best-practices

What problem does it solve?

This guidance reduces drift and ambiguity in project specifications by prescribing how to author, place, and maintain SPEC.md files so that behavior, requirements, and acceptance criteria remain discoverable, testable, and aligned with implementation.

Core Features & Use Cases

• Naming & placement rules: mandates a single root SPEC.md per scope and colocated placement for project, app, and package-level specs.
• Content checklist: requires Problem and solution, Domain model, REQ-* identifiers, Invariants, Non-goals, Acceptance criteria checklists, and conditional risk tags and test traceability.
• Lifecycle & mutation policy: advises evidence-based authoring, retroactive spec practices, mutation rules, and retirement guidance; useful when running specalign or entering the SPEC gate.
• Use case: during a SPEC gate review, run this checklist to surface missing REQ IDs, absent acceptance criteria, or spec/code drift before approval.

Quick Start

Use this guidance to review the SPEC.md at the target path and produce a checklist of missing required sections, REQ-* identifiers, and any drift between the spec and implementation.