Ideation & refinement

Pulse exposes 23 of its 198 MCP tools for the first two pipeline stages — turning a raw request into a derived spec:

12 ideation tools (server.py:3318–4538, plus delete_spec_from_ideation derivation alias) — the intake stage. Captures the request, runs scope evaluation, and either advances directly to a spec or branches into refinement.
11 refinement tools (server.py:4539–5460, plus snapshots at server.py:10975–11067) — the deep-investigation stage. Source files, KG queries, runtime logs, and stakeholder answers become citable evidence before a spec contract is written.

Cross-cutting concerns — Q&A, knowledge entries, attachments, architecture, mockups — live on their own reference pages. This page focuses on the lifecycle, scope evaluation, and spec-derivation tools. Source-of-truth citations: okto-pulse-feature-inventory.md:290–314 (ideation tools), :315–332 (refinement tools), :446–456 (refinement snapshots), :967–981 (status enums), :982–1021 (governance gates).

When to use what

Stage	Why it exists	Output
Ideation	Capture a raw, possibly-vague request and kill ambiguity before spec work begins.	A scope-assessed ideation in `refined` state.
Refinement (optional)	Investigate the codebase, query the KG, and lock down constraints before writing a spec.	An approved refinement with citable findings, evidence, and constraints.
Spec derivation	Promote either an ideation or a refinement into a spec contract pre-populated with everything captured upstream.	A new spec in `draft` state, ready for acceptance criteria and test scenarios.

A simple feature can skip refinement entirely — call okto_pulse_derive_spec_from_ideation once the ideation reaches refined. Use refinement when the request needs investigation that will outlive the ideation: which storage backend, which library, what the existing code already does.

Status flow and gates

Source: okto-pulse-core/src/okto_pulse/core/models/db.py (status enums) and permissions.py (transition gates).

Stage	Transition	MCP tool	Gate
Ideation	`draft → evaluating`	`okto_pulse_move_ideation`	none
Ideation	`evaluating → refined`	`okto_pulse_move_ideation`	scope evaluation submitted; ambiguity score below threshold
Ideation	`refined → done`	`okto_pulse_move_ideation`	spec derived (`derive_spec_from_ideation`) or refinement approved
Refinement	`draft → in_progress`	`okto_pulse_move_refinement`	none
Refinement	`in_progress → review`	`okto_pulse_move_refinement`	findings, evidence, and constraints recorded
Refinement	`review → approved`	`okto_pulse_move_refinement`	manual approval (board permission)
Refinement	`approved → done`	`okto_pulse_move_refinement`	spec derived (`derive_spec_from_refinement`)

The transitions are enforced server-side. A client cannot move an ideation to refined without first submitting okto_pulse_evaluate_ideation, and cannot move a refinement to review without populating findings, evidence, and constraints. See okto-pulse-feature-inventory.md:982–1021 for the full gate list.

Tool index

Ideation lifecycle (7)

create_ideation, get_ideation, get_ideation_context, list_ideations, update_ideation, move_ideation, delete_ideation.

Refinement lifecycle (7)

create_refinement, get_refinement, get_refinement_context, list_refinements, update_refinement, move_refinement, delete_refinement.

Scope evaluation (1)

evaluate_ideation — three-axis score (domains, ambiguity, dependencies) with written justification per axis.

Spec derivation (2)

derive_spec_from_ideation, derive_spec_from_refinement — pre-populate a spec from upstream artifacts.

Snapshots & history (6)

Per-stage list_*_snapshots, get_*_snapshot, get_*_history for ideation and refinement.

For Q&A on either stage, see Comments & questions. For attaching reference docs, see Knowledge & attachments. For architecture diagrams and mockups, see Architecture & mockups.

Ideation lifecycle

`okto_pulse_create_ideation`

Source: server.py:3319. Create an ideation with a title, description, and initial context.

board_id:    "brd_abc123"
title:       "Per-user rate limiting on /search"
description: "Burst 20 req/s, sustained 5 req/s. Return 429 + Retry-After."
context:     "No rate limiting exists today. Load tests show search abuse."

`okto_pulse_get_ideation`

Source: server.py:3388. Returns the ideation with its Q&A, knowledge, and submitted scope assessment (if any).

`okto_pulse_get_ideation_context`

Source: server.py:3468. Use this — not get_ideation — before advancing the ideation or deriving a spec. It returns the rich bundle: ideation core fields plus linked refinements plus a Knowledge Graph context block (similar prior decisions, related entities). This is what saves an agent from re-discovering decisions another agent already recorded.

`okto_pulse_list_ideations`

Source: server.py:3573. List ideations on a board, optionally filtered by status (draft / evaluating / refined / done).

`okto_pulse_update_ideation`

Source: server.py:3634. Update title, description, context, or scope_assessment. Calling this from refined status snapshots the previous version so history is preserved.

`okto_pulse_move_ideation`

Source: server.py:3716. Advance ideation status. The state machine enforces draft → evaluating → refined → done; backward transitions (refined_to_draft) require the dedicated permission flag.

ideation_id: "ide_5fa9..."
to_status:   "evaluating"

`okto_pulse_delete_ideation`

Source: server.py:3782. Permanently delete an ideation. Linked refinements and derived specs become orphaned; prefer archive_tree (see Architecture & mockups) when you need a soft-delete with restore.

Scope evaluation

`okto_pulse_evaluate_ideation`

Source: server.py:3813. Submit a three-axis scope evaluation. Each axis takes a numeric score (1–5) and a written justification — Pulse rejects score-only submissions.

Axis	What it measures
`domains`	How many product surfaces the request touches (1 = single module, 5 = cross-cutting)
`ambiguity`	How under-specified the request still is (1 = crystal clear, 5 = needs significant Q&A)
`dependencies`	How much external work this depends on (1 = no new infra, 5 = blocked on external teams)

ideation_id:             "ide_5fa9..."
domains_score:           2
domains_justification:   "API layer + observability dashboards."
ambiguity_score:         3
ambiguity_justification: "Burst budget per IP vs per session is unspecified."
dependencies_score:      1
dependencies_justification: "No new infra needed; Redis already in stack."

An ambiguity score of 4 or 5 blocks the evaluating → refined transition. Use okto_pulse_ask_ideation_choice_question (see Comments & questions) to drive structured answers that pin scope down before re-submitting an evaluation.

`okto_pulse_create_refinement`

Source: server.py:4540. Create a refinement linked to an ideation that has reached refined status.

ideation_id: "ide_5fa9..."
title:       "Investigate rate-limit storage backends"
description: "Compare Redis token-bucket vs in-memory leaky-bucket."

`okto_pulse_get_refinement`

Source: server.py:4645. Return the refinement with its Q&A and knowledge entries.

`okto_pulse_get_refinement_context`

Source: server.py:4717. Rich bundle: refinement + parent ideation + KG context + prior decisions ranked by similarity. Call this before recording any new finding — the KG section often surfaces a decision already on the graph for the same problem.

`okto_pulse_list_refinements`

Source: server.py:4825. List refinements on an ideation.

`okto_pulse_update_refinement`

Source: server.py:4890. Update findings, evidence, and constraints. These three fields are the gate evidence — the in_progress → review transition checks that they are non-empty.

refinement_id: "rfn_3c01..."
findings:      "Redis token-bucket preferred. Leaky-bucket adds 6ms p99 vs 0.8ms; see middleware/rate_limit.py:117–143."
evidence:      ["src/okto_pulse/community/middleware/rate_limit.py:117–143",
                "kg://decisions/dec_e7ca... — 'Use Redis for ephemeral counters'",
                "load-tests/2026-05-06-baseline.json"]
constraints:   "Must work with Redis 7.x cluster mode. Must fall back to allow on Redis outage."

Pulse explicitly rejects “copying stale repo docs without source verification” as a refinement anti-pattern. Evidence must be checkable against the current codebase — path:line references, KG query outputs, runtime artifacts. An agent that records vague findings has not completed refinement.

`okto_pulse_move_refinement`

Source: server.py:4979. Advance refinement status. Each gate is enforced server-side and cannot be bypassed.

`okto_pulse_delete_refinement`

Source: server.py:5044. Permanently delete a refinement.

Spec derivation

Both derivation tools create a new spec pre-populated with content captured upstream. Knowledge entries propagate; architecture designs cascade; the parent’s Q&A history is referenced via foreign key. The parent transitions to done once derivation succeeds.

`okto_pulse_derive_spec_from_ideation`

Source: server.py:3905. Create a spec from a refined-status ideation. Use this when the ideation is straightforward and refinement is unnecessary.

ideation_id: "ide_5fa9..."

`okto_pulse_derive_spec_from_refinement`

Source: server.py:5075. Create a spec from an approved-status refinement. Findings, evidence, and constraints become draft spec content. Use this when the refinement uncovered work that the spec must encode (decisions to record, constraints to honour).

refinement_id: "rfn_3c01..."

After either call, switch to the Spec tools reference to add acceptance criteria, business rules, test scenarios, decisions, and API contracts.

Snapshots and history

Versioning is automatic — each meaningful update creates a snapshot you can list or replay. History is the per-field edit log.

Tool	Line	Description
`okto_pulse_list_ideation_snapshots`	`server.py:3981`	List versioned snapshots of an ideation
`okto_pulse_get_ideation_snapshot`	`server.py:4026`	Get a snapshot by version number
`okto_pulse_get_ideation_history`	`server.py:4076`	Paginated per-field edit log
`okto_pulse_list_refinement_snapshots`	`server.py:10975`	List versioned snapshots of a refinement
`okto_pulse_get_refinement_snapshot`	`server.py:11019`	Get a snapshot by version number
`okto_pulse_get_refinement_history`	`server.py:5149`	Paginated per-field edit log

Permissions

Action	Permission flag
Create ideation / refinement	`Permissions.IDEATION_CREATE`, `Permissions.REFINEMENT_CREATE`
Update ideation / refinement	`Permissions.IDEATION_UPDATE`, `Permissions.REFINEMENT_UPDATE`
Move ideation / refinement (forward)	`Permissions.IDEATION_MOVE`, `Permissions.REFINEMENT_MOVE`
Move backward (`refined_to_draft`, `validated_to_draft`)	`Permissions.IDEATION_MOVE_BACKWARD`, `Permissions.REFINEMENT_MOVE_BACKWARD`
Submit `evaluate_ideation`	`Permissions.IDEATION_EVALUATE`
Derive a spec	`Permissions.SPECS_CREATE`
Delete ideation / refinement	`Permissions.IDEATION_DELETE`, `Permissions.REFINEMENT_DELETE`
Read snapshots / history	`Permissions.BOARD_READ`

A blocked call returns FORBIDDEN. Adjust the agent’s preset in Board → Agents → Edit.

Errors

{
  "error": "CONFLICT",
  "message": "Cannot move ideation to 'refined' — ambiguity score is 4. Reduce ambiguity via Q&A and resubmit evaluate_ideation.",
  "detail": {"current_ambiguity_score": 4, "max_allowed": 3}
}

Code	Most common cause
`VALIDATION_ERROR`	Missing axis justification on `evaluate_ideation`; empty `findings` / `evidence` / `constraints` when moving to `review`.
`NOT_FOUND`	Ideation / refinement ID belongs to a different board, or parent ideation does not exist for `create_refinement`.
`FORBIDDEN`	Agent’s preset does not include the required permission flag.
`CONFLICT`	Status transition not allowed (e.g. moving an ideation to `refined` with an ambiguity score above threshold; deriving a spec from an ideation that is not `refined`).

Next steps

Specs

Acceptance criteria, business rules, test scenarios, decisions, API contracts, evaluation gate, validation gate.

Comments & questions

The ambiguity-killer Q&A protocol and free-form comments across stages.

Knowledge & attachments

Reference docs and binary files attached to ideations and refinements.

ADLC pipeline

Where ideation and refinement fit in the end-to-end flow.

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Documentation Index

​Ideation & refinement

​When to use what

​Status flow and gates

​Tool index

Ideation lifecycle (7)

Refinement lifecycle (7)

Scope evaluation (1)

Spec derivation (2)

Snapshots & history (6)

​Ideation lifecycle

​okto_pulse_create_ideation

​okto_pulse_get_ideation

​okto_pulse_get_ideation_context

​okto_pulse_list_ideations

​okto_pulse_update_ideation

​okto_pulse_move_ideation

​okto_pulse_delete_ideation

​Scope evaluation

​okto_pulse_evaluate_ideation

​Refinement lifecycle

​okto_pulse_create_refinement

​okto_pulse_get_refinement

​okto_pulse_get_refinement_context

​okto_pulse_list_refinements

​okto_pulse_update_refinement

​okto_pulse_move_refinement

​okto_pulse_delete_refinement

​Spec derivation

​okto_pulse_derive_spec_from_ideation

​okto_pulse_derive_spec_from_refinement

​Snapshots and history

​Permissions

​Errors

​Next steps

Specs

Comments & questions

Knowledge & attachments

ADLC pipeline

Ideation & refinement

When to use what

Status flow and gates

Tool index

Ideation lifecycle

`okto_pulse_create_ideation`

`okto_pulse_get_ideation`

`okto_pulse_get_ideation_context`

`okto_pulse_list_ideations`

`okto_pulse_update_ideation`

`okto_pulse_move_ideation`

`okto_pulse_delete_ideation`

Scope evaluation

`okto_pulse_evaluate_ideation`

Refinement lifecycle

`okto_pulse_create_refinement`

`okto_pulse_get_refinement`

`okto_pulse_get_refinement_context`

`okto_pulse_list_refinements`

`okto_pulse_update_refinement`

`okto_pulse_move_refinement`

`okto_pulse_delete_refinement`

Spec derivation

`okto_pulse_derive_spec_from_ideation`

`okto_pulse_derive_spec_from_refinement`

Snapshots and history

Permissions

Errors

Next steps