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.

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.

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.

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.

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.

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Spec

Spec

What is a spec

Spec anatomy

States and gates

Spec evaluation

Spec validation gate

Deriving cards from a spec

Spec knowledge and Q&A

Decisions on a spec

​Spec

​What is a spec

​Spec anatomy

​States and gates

​Spec evaluation

​Spec validation gate

​Deriving cards from a spec

​Spec knowledge and Q&A

​Decisions on a spec

​Related pages

Spec

What is a spec

Spec anatomy

States and gates

Spec evaluation

Spec validation gate

Deriving cards from a spec

Spec knowledge and Q&A

Decisions on a spec

Related pages