> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oktolabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec

> The contract artifact that turns refined intent into gated implementation work.

# Spec

You can use a spec as the implementation contract for a feature. It is where Pulse turns refined intent into requirements, acceptance criteria, test scenarios, API contracts, decisions, and traceability that cards can implement.

## What is a spec

A spec is the central artifact in Pulse. Ideations and refinements feed it; sprints and cards derive from it. Validation gates protect it from becoming an unreviewed prompt dump.

## Spec anatomy

A complete spec usually contains:

| Area                     | What belongs there                                                           |
| ------------------------ | ---------------------------------------------------------------------------- |
| Title and description    | The smallest accurate name for the work and the business outcome.            |
| Context                  | Why this work exists and what constraints shape it.                          |
| Functional requirements  | User-visible behavior and workflow expectations.                             |
| Technical requirements   | Architecture, performance, storage, permission, and integration constraints. |
| Acceptance criteria      | Observable conditions that make the spec acceptable.                         |
| Test scenarios           | Evidence-oriented checks linked to future cards.                             |
| Business rules           | Rules that must not drift during implementation.                             |
| API contracts            | Request, response, error, and compatibility expectations.                    |
| Mockups and architecture | Visual and structural context.                                               |
| Decisions                | Formal choices with rationale, alternatives, and supersedence links.         |

## States and gates

| State         | Meaning                                             |
| ------------- | --------------------------------------------------- |
| `draft`       | Editable working version.                           |
| `review`      | Ready for qualitative review.                       |
| `approved`    | Evaluation passed and content can enter validation. |
| `validated`   | Content evidence gate passed; the spec is locked.   |
| `in_progress` | Cards are being implemented from the spec.          |
| `done`        | Spec work is complete.                              |
| `cancelled`   | Spec should not proceed.                            |

Backward moves exist for controlled edits: `approved_to_draft` and `validated_to_draft` clear the active lock while preserving validation history.

## Spec evaluation

Spec evaluation is the qualitative gate. It checks completeness, assertiveness, ambiguity, and readiness. The docs use `80` as the default acceptance threshold: below that, revise the spec before promoting it.

```text theme={null}
okto_pulse_submit_spec_evaluation
okto_pulse_move_spec
```

## Spec validation gate

Spec validation is separate from evaluation. `okto_pulse_submit_spec_validation` records evidence that the approved spec meets the content requirements for `approved -> validated`. Validator is the intended gate-holder role.

<Warning>
  Do not treat `approved` and `validated` as synonyms. `approved` means the spec looks acceptable; `validated` means the evidence gate passed and the spec is locked for implementation.
</Warning>

## Deriving cards from a spec

Cards are derived after the spec is validated or otherwise approved for implementation. Derived cards should link back to the spec and to test scenarios, business rules, API contracts, technical requirements, or decisions where relevant.

```text theme={null}
okto_pulse_derive_cards_from_spec
okto_pulse_link_task_to_scenario
okto_pulse_link_task_to_rule
okto_pulse_link_task_to_contract
okto_pulse_link_task_to_tr
```

## Spec knowledge and Q\&A

Specs can carry Q\&A and knowledge attachments. Use those when implementation agents need durable answers or source material. Do not hide critical requirements only in comments; promote them into spec fields when they affect acceptance.

## Decisions on a spec

A Decision records why a choice was made. Use `okto_pulse_add_decision` for tradeoffs, architecture choices, data model decisions, and security boundaries. Use `supersedes_decision_id` when replacing an older choice so the Knowledge Graph can preserve the chain.

## Related pages

* [Validation gates](/concepts/validation)
* [Decisions](/concepts/decisions)
* [Spec tools](/reference/mcp/specs)
* [Spec flags](/permissions/spec)