Spec Patterns

Spec-as-PR

Open a PR containing only .flow/specs/<id>.md. Review the spec before code lands. This moves the high-leverage discussion upstream.

flowchart LR
  Branch["feature branch"] --> Spec["Spec-only PR"]
  Spec --> Product["Product review"]
  Spec --> Tech["Technical review"]
  Product --> Frozen["Frozen R-IDs"]
  Tech --> Frozen
  Frozen --> Implementation["Implementation PR"]

Use this when a spec crosses team boundaries, user-facing behavior, permissions, data migrations, billing, or production risk. Reviewing a spec-only PR is much cheaper than reviewing a finished implementation that encoded the wrong product decision.

Frozen-at-handover

After a spec is reviewed, R-IDs do not change meaning. New criteria append. Removed criteria leave gaps.

Symmetric interview

Use a business pass and technical pass on one spec:

/flow-next:interview fn-1 --scope=business
/flow-next:interview fn-1 --scope=technical

The technical pass reads business sections before asking implementation questions.

Decision records

Record load-bearing decisions only when they are hard to reverse, surprising without context, and represent a real trade-off.

Constraint ledger

For team specs, keep constraints visible instead of burying them in prose:

Constraint	Example
Product boundary	”Do not add billing plan management.”
Technical boundary	”No database migration in this spec.”
Compatibility	”Existing config files continue to load.”
Operational	”Failure must leave .flow/ state valid.”
Security	”No secrets are written to receipts.”

The ledger keeps the agent from optimizing away a constraint that a human assumed was obvious.

Evidence-first tasks

Ask each task to name its evidence before it starts:

Evidence expected:
- Unit test for invalid dependency references
- `flowctl validate --all`
- Updated docs page for dependency behavior

This makes “done” concrete and improves the PR cognitive aid later.

Repair loop

When review finds a gap, fix the artifact that caused it:

Finding	Fix
Requirement misunderstood	Update the spec.
Task skipped a requirement	Update task graph or rerun /flow-next:plan.
Code defect	Rerun /flow-next:work on the affected task.
Review false positive	Record suppression or validator evidence.
Reviewer confused	Improve /flow-next:make-pr body or docs.

Do not let the chat transcript become the source of truth. Put the fix back into .flow/.