# SPEC.md

> Turn an intended outcome into testable behavior, requirements, constraints, non-goals, edge cases, and acceptance evidence before selecting implementation details or decomposing the work.

**Decision rule:** Specify what and why before deciding how. If a statement cannot be verified, clarified, or traced to a user outcome, tighten it before planning.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Problem and outcome

> Define the user-visible change and the evidence that it matters.

- **Problem:** <Describe the current workflow, pain, and affected user>
- **Desired outcome:** <State the observable behavior or state change>
- **Success measures:** <List product, quality, safety, and operational measures>

## Requirements and scenarios

> Write behavior precisely enough that each scenario can become an objective acceptance test.

- **Primary scenarios:** <List trigger, inputs, expected behavior, and output for each core path>
- **Edge scenarios:** <Cover missing, malformed, conflicting, unauthorized, canceled, and repeated actions>
- **Data:** <Define required fields, provenance, retention, correction, and deletion>

## Constraints and non-goals

> Prevent the implementation from silently expanding or violating a hard boundary.

- **Constraints:** <State security, privacy, compatibility, latency, cost, and compliance limits>
- **Non-goals:** <List plausible adjacent work explicitly excluded>
- **Open questions:** <Record unresolved ambiguity, owner, and deadline for each answer>

## Acceptance and traceability

> Connect each requirement to evidence and later implementation work.

- **Acceptance checks:** <Write objective checks for every required behavior and important failure path>
- **Approval:** <Name the product, design, security, legal, or operations reviewers required>
- **Traceability:** <Link plan decisions, tasks, tests, eval cases, telemetry, and release evidence>

## Related AgentAtlas field guides

- [Specifications](https://agentatlas.dev/topics/specifications)
- [Agent product design](https://agentatlas.dev/topics/agent-product-design)
- [Evals and verification](https://agentatlas.dev/topics/evals-verification)

## Primary references

- [GitHub Spec Kit](https://github.github.com/spec-kit/index.html) — The specification-driven workflow from intent through specification, plan, tasks, implementation, and quality checks.
- [AGENTS.md specification](https://agents.md/) — Portable repository-level instructions that keep implementation constraints and verification commands available to coding agents.
- [Human-in-the-loop](https://openai.github.io/openai-agents-python/human_in_the_loop/) — Pause, inspect, approve, reject, persist, and resume patterns for consequential tool calls across agent runs.
- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — Transparency, explicit planning, tool-interface design, and choosing agentic complexity only when it improves outcomes.
- [Evaluation best practices](https://developers.openai.com/api/docs/guides/evaluation-best-practices) — Eval design, task-specific datasets, graders, continuous evaluation, and avoiding common measurement mistakes.
- [Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) — Agent-specific evaluation design, outcome and process measures, transcript analysis, and iterative improvement.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.