Skip to main content

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

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:
AreaWhat belongs there
Title and descriptionThe smallest accurate name for the work and the business outcome.
ContextWhy this work exists and what constraints shape it.
Functional requirementsUser-visible behavior and workflow expectations.
Technical requirementsArchitecture, performance, storage, permission, and integration constraints.
Acceptance criteriaObservable conditions that make the spec acceptable.
Test scenariosEvidence-oriented checks linked to future cards.
Business rulesRules that must not drift during implementation.
API contractsRequest, response, error, and compatibility expectations.
Mockups and architectureVisual and structural context.
DecisionsFormal choices with rationale, alternatives, and supersedence links.

​
States and gates

StateMeaning
draftEditable working version.
reviewReady for qualitative review.
approvedEvaluation passed and content can enter validation.
validatedContent evidence gate passed; the spec is locked.
in_progressCards are being implemented from the spec.
doneSpec work is complete.
cancelledSpec 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.
Last modified on May 8, 2026