> ## 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. # The SDLC Pipeline > How Pulse moves work from raw idea to validated card — and why each gate exists Every software idea that enters Pulse travels through six stages before code ships. The stages are not advisory — they are enforced status transitions in the service layer. An agent cannot skip a stage by moving a card directly; it must call the MCP tools that correspond to each transition, and each transition checks its gate before proceeding. This page explains what happens at each stage, what the enforced thresholds are, and what gets written to the Knowledge Graph along the way. *** ## The 6-stage pipeline ```mermaid theme={null} flowchart LR I([Ideation\ndraft → refined]) R([Refinement\ndraft → approved]) S([Spec\ndraft → validated]) SP([Sprint\ndraft → active]) C([Card\nnot_started → validation]) V([Validation\nvalidation → done]) I -->|derive_spec| R R -->|derive_spec| S S -->|suggest_sprints| SP SP -->|create_card| C C -->|submit_task_validation| V V -->|kg_commit_consolidation| KG[(Knowledge\nGraph)] ``` Each arrow represents a Pulse MCP tool call. The pipeline is linear by default — though multiple ideations, refinements, and sprints can exist on a board simultaneously, each one follows its own path through the stages. **Status enums** (source: `okto-pulse-core/src/okto_pulse/core/models/db.py`): | Stage | Statuses | | ---------- | ----------------------------------------------------------------------------- | | Ideation | `draft` → `evaluating` → `refined` → `done` | | Refinement | `draft` → `in_progress` → `review` → `approved` → `done` | | Spec | `draft` → `review` → `approved` → `validated` → `in_progress` → `done` | | Sprint | `draft` → `active` → `review` → `closed` | | Card | `not_started` → `started` → `in_progress` ⇄ `on_hold` → `validation` → `done` | *** ## Stage 1: Ideation Ideation is the intake stage. You give Pulse a raw request — one sentence or a paragraph — and Pulse surfaces every material gap before anything gets built. **The core problem ideation solves:** vague requests produce vague specs. Instead of prompting you to write a spec up-front, Pulse asks questions about the gaps it finds in the raw text. **What an agent does here:** 1. Create the ideation: `okto_pulse_create_ideation` 2. Evaluate scope — three axes, each justified in writing: `okto_pulse_evaluate_ideation` 3. Ask ambiguity-killer questions (text or choice): `okto_pulse_ask_ideation_question`, `okto_pulse_ask_ideation_choice_question` 4. Record answers: `okto_pulse_answer_ideation_question` 5. Advance when ready: `okto_pulse_move_ideation` (`draft → evaluating → refined`) **Gate:** Pulse will not advance an ideation with an ambiguity score above the configured threshold. The scope assessment returns three numeric scores (domains, ambiguity, dependencies) with per-axis justification — not just numbers. An ambiguity score of 4/5 means the ideation needs more Q\&A before refinement. **What gets written to the KG:** Nothing is consolidated at ideation. Knowledge attached to an ideation (`okto_pulse_add_ideation_knowledge`) is available to downstream stages but is not yet promoted to the graph. The ambiguity-killer protocol is most useful for requests that contain vague verbs ("add authentication"), undefined nouns ("the admin panel"), or implicit scope ("make it faster"). The more precisely you answer the questions here, the more accurate the derived spec will be. *** ## Stage 2: Refinement Refinement is investigation, not paraphrasing. Its job is to read the actual codebase, query the KG for prior decisions, and produce a concrete evidence-backed description of current behavior, constraints, and dependencies. **What distinguishes refinement from a chat conversation:** the evidence must be citable. Good refinement output includes source file references (`path:line`), KG query results, runtime logs, and stakeholder answers. An agent that produces vague findings has not completed refinement. **What an agent does here:** 1. Create a refinement linked to the ideation: `okto_pulse_create_refinement` 2. Query the KG for prior decisions before deciding anything: `okto_pulse_kg_find_similar_decisions`, `okto_pulse_kg_query_natural` 3. Update findings, evidence, and constraints: `okto_pulse_update_refinement` 4. Advance when evidence is complete: `okto_pulse_move_refinement` (`draft → in_progress → review → approved`) 5. Derive a spec from the approved refinement: `okto_pulse_derive_spec_from_refinement` **Gate:** Refinement moves to `approved` only when evidence, findings, and constraints are recorded. The derived spec is pre-populated from refinement output — not written from scratch. **What gets written to the KG:** Refinement knowledge entries attached via `okto_pulse_add_refinement_knowledge` become candidates for the consolidation queue when the downstream spec is consolidated. Pulse rejects "copying stale repo docs without source verification" as an explicit anti-pattern. Refinement evidence must be checked against the current codebase state, not assumed from memory. *** ## Stage 3: Spec The spec is the implementation contract. It answers "what must be true when this ships?" with enough precision that a different agent (or a different session of the same agent) could implement it without guessing. **A strong spec includes:** * Problem statement * Acceptance criteria (each linked to at least one test scenario) * Functional requirements → business rule linkage * Technical requirements * Test scenarios with AC coverage * Business rules → card linkage * API contracts * Architecture decisions * Non-goals (explicit scope exclusion) **What an agent does here:** 1. Spec is created automatically via `okto_pulse_derive_spec_from_ideation` or `okto_pulse_derive_spec_from_refinement` 2. Add test scenarios with AC linkage: `okto_pulse_add_test_scenario` 3. Add business rules: `okto_pulse_add_business_rule` 4. Record design decisions with alternatives: `okto_pulse_add_decision` 5. Add API contracts: `okto_pulse_add_api_contract` 6. Submit evaluation (score + narrative): `okto_pulse_submit_spec_evaluation` 7. Submit validation (completeness/assertiveness/ambiguity): `okto_pulse_submit_spec_validation` 8. Advance: `okto_pulse_move_spec` **Spec evaluation gate (score ≥ 80):** `okto_pulse_submit_spec_evaluation` requires a qualitative score and written narrative. The gate for `validated → in_progress` will not pass if the evaluation score is below threshold. **Spec validation gate:** `okto_pulse_submit_spec_validation` requires three threshold checks — completeness, assertiveness, and ambiguity scores with written evidence. Success locks the spec content. An agent cannot modify a validated spec without explicitly unlocking it via `approved_to_draft` or `validated_to_draft`. **Spec → done gate (4 coverage checks + 2 structural checks):** 1. 100% acceptance criteria → test scenario coverage 2. FR → BR linkage complete 3. BR → Card linkage complete 4. AC → Scenario linkage complete 5. Configurable decision coverage threshold met 6. No non-bug tasks still open **What gets written to the KG on consolidation:** Spec is the richest KG source. The consolidation pipeline writes `Decision`, `Criterion`, `Constraint`, `Requirement`, `APIContract`, and `TestScenario` nodes, plus `belongs_to`, `derives_from`, `tests`, and `implements` edges. These nodes persist in the per-board LadybugDB graph (`~/.okto-pulse/boards/{id}/graph.lbug`) and survive the next session. The spec is where most of the KG value is created. Every `okto_pulse_add_decision` call with alternatives and justification becomes a queryable `Decision` node that future agents can retrieve via `okto_pulse_kg_find_similar_decisions` before making the same call again. *** ## Stage 4: Sprint A sprint slices a validated spec into reviewable work. Sprints define the scope, objective, and expected outcome for a batch of cards. They are not a time-box — they are a logical delivery slice. **What an agent does here:** 1. Get sprint suggestions from the spec: `okto_pulse_suggest_sprints` 2. Create the sprint with objective and expected outcome: `okto_pulse_create_sprint` 3. Assign cards to the sprint: `okto_pulse_assign_tasks_to_sprint` 4. Resolve sprint Q\&A before execution: `okto_pulse_ask_sprint_question`, `okto_pulse_answer_sprint_question` 5. Submit sprint evaluation before activating: `okto_pulse_submit_sprint_evaluation` 6. Advance: `okto_pulse_move_sprint` (`draft → active`) **Sprint evaluation gate:** `okto_pulse_submit_sprint_evaluation` is the quality gate for `review → closed`. A sprint cannot close without a recorded evaluation. This prevents sprints from being silently abandoned. **What gets written to the KG:** Sprint consolidation writes `Entity` and `Requirement` nodes representing the sprint scope, plus `belongs_to` edges linking sprint cards back to spec decisions. *** ## Stage 5: Cards (Tasks and Bugs) Cards are execution units. Each card must be self-contained — an implementer agent should be able to work from a card alone without reading the spec from scratch. **Card types:** `normal`, `test`, `bug` **What an agent does before starting a card:** 1. Get the full context bundle: `okto_pulse_get_task_context` — returns card + spec + business rules + test scenarios + decisions + KG context in one call 2. Copy needed artifacts: `okto_pulse_copy_knowledge_to_card`, `okto_pulse_copy_mockups_to_card`, `okto_pulse_copy_architecture_to_card` 3. Advance: `okto_pulse_move_card` (`not_started → started → in_progress`) **Card → validation → done gate:** When implementation is complete, the card moves to `validation` (not directly to `done`). To move from `validation → done`, the closing agent must provide: 1. `conclusion` — written summary of what was done 2. `completeness` (0–100) — with written justification (e.g., "90 — pagination implemented but not yet perf-tested") 3. `drift` (0–100) — deviation from the original spec, with justification (e.g., "10 — switched from JWT to session tokens per spec amendment") 4. If the Task Validation Gate is enabled: an independent reviewer must call `okto_pulse_submit_task_validation` — auto-fail on threshold violations even if the reviewer recommends approval **Test theater prevention gate:** `okto_pulse_update_test_scenario_status` requires structured evidence: `test_file_path`, `test_function`, `last_run_at`, and `output_snippet` or `test_run_id`. Marking a test "passed" without evidence is rejected. Sprint close re-validates this evidence on every passed scenario. **Bug card gate (test-first):** 1. A new failing test scenario must exist before the bug card can move to `in_progress` 2. A linked test card must exist **Card status transitions:** `not_started → started → in_progress ⇄ on_hold → validation → done` **What gets written to the KG:** Completed cards contribute `Learning` nodes (lessons from implementation) and `Bug` nodes (linked via `validates` edges to the test scenarios that caught them). The `learning_from_bugs` query (`okto_pulse_kg_get_learning_from_bugs`) surfaces these across future sessions. *** ## Stage 6: Validation Validation is the independent quality checkpoint. It is separated from implementation by design — the agent that built the card cannot be the same agent that validates it (enforced by permission presets). **Permission presets** (source: `okto-pulse-core/src/okto_pulse/core/models/db.py:PermissionPreset`): | Preset | Gate permissions | | --------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Executor** | Can move cards `not_started → validation`. Cannot submit validation gates. | | **Validator** | Can submit `spec_validation`, `spec_evaluation`, `sprint_evaluation`, `task_validation`. Can move cards `validation → done`. | | **QA** | Can write test scenarios. Cannot submit any gate. | | **Spec Writer** | Owns ideation/refinement/spec content. Cannot move specs past `approved`. | **What a validator agent does:** 1. Read the card with context: `okto_pulse_get_task_validation` 2. Verify the implementation evidence (logs, test output, screenshots) 3. Submit with structured evidence: `okto_pulse_submit_task_validation` Good validation evidence: exact commands run, relevant logs or output, test names, known limitations, unresolved risks. **What gets written to the KG:** After a successful validation, `okto_pulse_kg_commit_consolidation` writes the durable decision and learning nodes for this card into the board's LadybugDB graph. *** ## Knowledge Graph integration Every stage produces artifacts that feed the Knowledge Graph. The KG is not a side effect — it is the durable memory layer that makes the next project faster. **11 node types written across the pipeline:** | Node type | Typically written at | | -------------- | ----------------------------------------------------------- | | `Decision` | Spec (design decisions), Ideation (choice question answers) | | `Criterion` | Spec (acceptance criteria, test scenarios) | | `Constraint` | Spec, Refinement (technical constraints) | | `Assumption` | Refinement (documented assumptions) | | `Requirement` | Spec (FRs, TRs), Sprint (scope) | | `Entity` | Spec (named entities), Sprint | | `APIContract` | Spec (API contracts) | | `TestScenario` | Spec (test scenarios) | | `Bug` | Card stage (bug cards) | | `Learning` | Card stage (post-implementation) | | `Alternative` | Spec (alternatives considered in decisions) | **10 relationship types** connect these nodes: `supersedes`, `contradicts`, `derives_from`, `relates_to`, `mentions`, `depends_on`, `violates`, `implements`, `tests`, `validates`. **What an agent can query mid-task:** ```text theme={null} okto_pulse_kg_query_natural("What auth approach did we decide?") okto_pulse_kg_find_similar_decisions("session token storage") okto_pulse_kg_find_contradictions() okto_pulse_kg_get_supersedence_chain(decision_id) okto_pulse_kg_get_learning_from_bugs("auth module") ``` These queries run against the embedded LadybugDB graph at `~/.okto-pulse/boards/{id}/graph.lbug`. They are deterministic (no LLM) and survive across sessions. The KG uses HNSW vector indexes on five node types for semantic search. *** ## Why this differs from a kanban A kanban answers "what is the current status of work?" Pulse answers "did the work satisfy the original intent?" — and refuses to close work that cannot prove it did. The structural differences: | Kanban | Pulse | | --------------------------------------- | ------------------------------------------------------------------------------- | | Columns represent status only | Status transitions enforce coverage gates | | Cards are created directly | Cards derive from validated specs | | Work is done when the developer says so | Work requires structured conclusion + completeness + drift evidence | | Context lives in chat history | Context lives in KG nodes that outlast sessions | | Moving a card requires one click | Moving a card from `validation → done` requires a validator agent with evidence | | No memory of past decisions | Prior decisions surface before new ones are made | The 216 MCP tools Pulse exposes are not shortcuts around this structure — they are the structure. An agent calls `okto_pulse_move_card` and the service layer checks every gate condition before the status changes. The traceability report (`okto_pulse_get_traceability_report`) returns the full lineage: spec → business rules → technical requirements → test scenarios → cards → validations. If a card exists that cannot be traced back to a spec requirement, it should not exist. *** ## Where to go next Walk through the full pipeline with a real example in 5 minutes. How the KG stores and serves decision history across sessions. Connect your agent to the 216 MCP tools that drive this pipeline. Deep-dive into Stage 1 — ambiguity reduction and scope assessment. Deep-dive into Stage 3 — writing implementation contracts. Deep-dive into Stage 6 — independent quality gates.