Spec Creation Updating

Overview

Produce specs that reduce ambiguity and can be implemented with minimal back-and-forth. Apply this workflow to any project domain (product, backend, API, data, UI, infrastructure, ops).

Workflow

1. Set boundaries

• Capture the objective and user/business value.
• Define in-scope and out-of-scope behavior.
• Record assumptions, dependencies, and constraints.
• Ask clarifying questions when decisions affect architecture, cost, security, or user-visible behavior.

2. Choose depth

• Write a lightweight spec for isolated, low-risk changes.
• Write a full system spec for cross-team, risky, or high-impact work.
• Keep the same quality gates regardless of depth.

3. Build structure

• Start from references/spec-template.md.
• Preserve repository naming, section ordering, and style if they already exist.
• Add domain-specific sections as needed, but do not remove mandatory content.

4. Fill concrete requirements

• Write requirements as testable statements, not intentions.
• Define success paths, edge cases, and failure behavior.
• Specify interfaces, data contracts, and state transitions when relevant.
• Specify non-functional requirements: performance, reliability, scalability, observability.
• When work spans existing code paths, add an implementation map that names the canonical files or directories to edit and adjacent paths that must remain untouched. Keep the map aligned with the repository's real structure so an implementer does not have to infer sibling paths from prose.
• For external, generated, AI-facing, or verifier-owned contracts, add a machine-checkable contract block before implementation details.

5. Define verification and completion

• Map each requirement to a verification method.
• Bind every requirement to a concrete verifier, test, or manual check ID; bind every verifier back to the requirement it proves.
• Include reproducible commands, tests, and manual checks when automation is unavailable.
• Define completion criteria with pass/fail outcomes.

6. Close traceability

• Link related specs, ADRs, designs, and operational docs.
• Update version, last-updated date, and status.
• Record unresolved questions and decision owners.

7. Run quality gate

• Validate against references/spec-must-have-checklist.md.
• Use references/spec-review-scorecard.md when auditing an existing spec.
• Treat any missing MUST item as blocking.

Writing rules

• Prefer precise language over broad terms like "optimize", "support", or "handle".
• Use explicit units, limits, and conditions.
• Mark implemented vs planned behavior with explicit status labels.
• Keep requirements and facts in the spec; keep narrative concise.
• Avoid embedding secrets or private credentials in reusable specs.

Machine-checkable contract blocks

Use this block when a contract crosses a subsystem boundary, drives generated data, constrains model/tool output, or owns verifier behavior.

Include:

• Canonical tokens, enum values, identifiers, and version fields.
• Predicate tables or mapping rules for eligibility, routing, projection, fallback, and publication decisions.
• App-owned envelope fields separated from model, user, service, or generated output.
• Validator order, fail-closed behavior, retry/idempotency rules, and forbidden silent-discard cases.
• Redaction and observability rules for logs, traces, QA artifacts, and analytics.
• Publication gates, rollout state, and backwards-compatibility rules when output becomes durable.
• Boundary-proof cases that show the exact allowed and disallowed edges.
• Requirement-to-verifier binding with stable IDs.

Do not rely on prose such as "validate the output" or "handle failures" when a table, enum list, state transition, or verifier binding would make the rule mechanically checkable.

Output expectations

• When creating a spec, deliver:
  • A complete spec document.
  • A list of unresolved questions.
  • A verification plan mapped to requirements.
• When reviewing a spec, deliver:
  • Prioritized gaps and risks.
  • Concrete rewrite suggestions.
  • A readiness verdict based on MUST items.