Spec Schema

Flow-Next specs follow the template in plugins/flow-next/templates/spec.md.

Required sections

• Goal and context
• Architecture and data models
• API contracts
• Edge cases and constraints
• Acceptance Criteria
• Boundaries
• Decision context

Recommended shape

---
id: fn-12-add-pr-cognitive-aid
title: Add PR cognitive aid generation
---

## Goal and Context

## Architecture and Data Models

## API Contracts

## Edge Cases and Constraints

## Acceptance Criteria

**R1:** ...
**R2:** ...

## Boundaries

## Decision Context

The exact template in the Flow-Next repository is the source of truth. This page explains how to think about the sections when writing or reviewing.

Acceptance Criteria

Acceptance criteria use stable R-IDs:

**R1:** The command creates `.flow/specs/<id>.md`.
**R2:** The command writes task files under `.flow/tasks/`.
**R3:** Validation fails if a task references a missing dependency.

Source tags

/flow-next:capture marks criteria with source tags:

• [user]: verbatim user requirement
• [paraphrase]: restated user requirement
• [inferred]: agent-inferred fill
• [strategy:<track>]: derived from STRATEGY.md

The read-back surfaces inferred counts before writing.

Section ownership

Section	Primary owner	Review question
Goal and context	PO, PM, user, maintainer	Does this describe the real outcome?
Acceptance criteria	PO + tech lead	Can we verify every requirement?
Boundaries	PO + tech lead	What must not be built?
Architecture and data models	Tech lead	Does this match the repo and constraints?
API contracts	Tech lead	Are integrations and compatibility clear?
Edge cases and constraints	PO + engineering	Are failure modes explicit enough?
Decision context	Whoever made the tradeoff	Will this still make sense in six months?

R-ID rules

• Use R1, R2, R3 in order.
• Freeze meanings after review.
• Leave gaps when removing accepted criteria.
• Append new criteria at the end.
• Map tasks back to R-IDs with satisfies: [R1, R3].

R-IDs are not formatting. They are how Flow-Next connects requirements to tasks, review receipts, and PR explanations.

Flow-Next 1.1.4 treats ## Acceptance Criteria as canonical. The parser still accepts legacy ## Acceptance and ## Acceptance criteria headings so older specs keep working.

Inferred criteria

Treat [inferred] criteria as provisional. They are useful because they show where the agent filled gaps, but they need human review before implementation. A high inferred count is a signal to run /flow-next:interview, not a signal to trust the draft harder.