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.
Refinement
You can use refinement when an ideation is promising but still needs investigation before it becomes a spec. Refinement is the deeper research stage between early idea and committed contract.What is a refinement and when to use it
A refinement is a structured investigation artifact. Use it when the team needs to inspect code paths, validate feasibility, collect constraints, compare options, or resolve dependencies before spec drafting. Use refinement instead of going straight from ideation to spec when the work crosses module boundaries, affects data storage, changes permissions, or depends on a behavior that must be proven in source.States
| State | Meaning |
|---|---|
draft | Investigation exists but has not started. |
in_progress | The agent is collecting evidence and answering open questions. |
review | Findings are ready for review. |
approved | The investigation is accepted and can feed a spec. |
done | Refinement is complete. |
cancelled | The investigation should stop. |
Deep investigation protocol
Refinement should produce evidence, not just a better-written idea. A useful refinement answers:- Which source files, APIs, routes, data models, or deployment constraints matter?
- Which assumptions were checked and which remain open?
- Which choices were rejected and why?
- What risk changes the spec or implementation plan?
Knowledge, mockups, and architecture
Refinement can carry the same supporting artifacts as ideation: knowledge, mockups, architecture diagrams, and Q&A. The difference is intent. Ideation artifacts clarify the problem; refinement artifacts prove implementation constraints.Deriving a spec from a refinement
Useokto_pulse_derive_spec_from_refinement after the refinement is approved. The resulting spec should be grounded in the refinement’s evidence, not just its summary.