> ## 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.
# Ideation & refinement
> Reference for the 23 MCP tools that drive the first two ADLC stages — capturing a raw idea, killing scope ambiguity with a structured Q&A, optionally running a deep-investigation refinement, and deriving a spec contract.
# Ideation & refinement
Pulse exposes **23 of its 216 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).
```mermaid theme={null}
flowchart LR
I_d([Ideation: draft]) --> I_e([evaluating]) --> I_r([refined]) --> I_done([done])
I_r -. derive_spec_from_ideation .-> S([Spec: draft])
I_r -. create_refinement .-> R_d([Refinement: draft])
R_d --> R_p([in_progress]) --> R_v([review]) --> R_a([approved]) --> R_done([done])
R_a -. derive_spec_from_refinement .-> S
```
| 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
`create_ideation`, `get_ideation`, `get_ideation_context`, `list_ideations`, `update_ideation`, `move_ideation`, `delete_ideation`.
`create_refinement`, `get_refinement`, `get_refinement_context`, `list_refinements`, `update_refinement`, `move_refinement`, `delete_refinement`.
`evaluate_ideation` — three-axis score (domains, ambiguity, dependencies) with written justification per axis.
`derive_spec_from_ideation`, `derive_spec_from_refinement` — pre-populate a spec from upstream artifacts.
Per-stage `list_*_snapshots`, `get_*_snapshot`, `get_*_history` for ideation and refinement.
For Q\&A on either stage, see [Comments & questions](/reference/mcp/comments-questions). For attaching reference docs, see [Knowledge & attachments](/reference/mcp/knowledge-attachments). For architecture diagrams and mockups, see [Architecture & mockups](/reference/mcp/architecture-mockups).
***
## Ideation lifecycle
### `okto_pulse_create_ideation`
Source: `server.py:3319`.
Create an ideation with a title, description, and initial context.
```text Input theme={null}
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."
```
```json Output theme={null}
{
"id": "ide_5fa9...",
"board_id": "brd_abc123",
"status": "draft",
"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.",
"scope_assessment": null,
"created_at": "2026-05-07T14:01:22Z"
}
```
### `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.
```text Input theme={null}
ideation_id: "ide_5fa9..."
to_status: "evaluating"
```
```json Output theme={null}
{
"id": "ide_5fa9...",
"status": "evaluating",
"moved_at": "2026-05-07T14:05:11Z"
}
```
### `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](/reference/mcp/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) |
```text Input theme={null}
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."
```
```json Output theme={null}
{
"id": "ide_5fa9...",
"scope_assessment": {
"domains": {"score": 2, "justification": "..."},
"ambiguity": {"score": 3, "justification": "..."},
"dependencies": {"score": 1, "justification": "..."}
},
"evaluated_at": "2026-05-07T14:08:42Z"
}
```
An ambiguity score of 4 or 5 blocks the `evaluating → refined` transition. Use `okto_pulse_ask_ideation_choice_question` (see [Comments & questions](/reference/mcp/comments-questions)) to drive structured answers that pin scope down before re-submitting an evaluation.
***
## Refinement lifecycle
### `okto_pulse_create_refinement`
Source: `server.py:4540`. Create a refinement linked to an ideation that has reached `refined` status.
```text Input theme={null}
ideation_id: "ide_5fa9..."
title: "Investigate rate-limit storage backends"
description: "Compare Redis token-bucket vs in-memory leaky-bucket."
```
```json Output theme={null}
{
"id": "rfn_3c01...",
"ideation_id": "ide_5fa9...",
"status": "draft",
"title": "Investigate rate-limit storage backends",
"description": "Compare Redis token-bucket vs in-memory leaky-bucket.",
"findings": null,
"evidence": null,
"constraints": null,
"created_at": "2026-05-07T14:35:09Z"
}
```
### `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.
```text Input theme={null}
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."
```
```json Output theme={null}
{
"id": "rfn_3c01...",
"status": "in_progress",
"findings": "Redis token-bucket preferred. ...",
"evidence": ["src/.../rate_limit.py:117–143", "kg://decisions/...", "..."],
"constraints": "Must work with Redis 7.x cluster mode. ...",
"updated_at": "2026-05-07T14:55:32Z"
}
```
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.
```text Input theme={null}
ideation_id: "ide_5fa9..."
```
```json Output theme={null}
{
"spec_id": "spc_b921...",
"ideation_id": "ide_5fa9...",
"status": "draft",
"title": "Per-user rate limiting on /search",
"derived_at": "2026-05-07T14:30:18Z"
}
```
### `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).
```text Input theme={null}
refinement_id: "rfn_3c01..."
```
```json Output theme={null}
{
"spec_id": "spc_d4b1...",
"refinement_id": "rfn_3c01...",
"ideation_id": "ide_5fa9...",
"status": "draft",
"derived_at": "2026-05-07T15:02:11Z"
}
```
After either call, switch to the [Spec tools](/reference/mcp/specs) 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
```json theme={null}
{
"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
Acceptance criteria, business rules, test scenarios, decisions, API contracts, evaluation gate, validation gate.
The ambiguity-killer Q\&A protocol and free-form comments across stages.
Reference docs and binary files attached to ideations and refinements.
Where ideation and refinement fit in the end-to-end flow.