Discovery
Technical discovery
Retire feasibility risk with time-boxed spikes, diagrams and decision records, and carry the answer into a change request and the working model.
Technical discovery answers the question "can we build this, and how?" before the team commits to a delivery date. It retires feasibility risk, and part of viability risk, such as running cost. Engineers own it, and they start at the same time as product discovery, not after it.
An engineer who joins discovery late meets a finished design and a fixed date. An engineer who joins early changes the design while it is still cheap to change.
Questions for technical discovery
| Question | Example | Typical output |
|---|---|---|
| Can the system do it at all? | Does SAP accept new vendors through its API? | A spike and a short write-up |
| How long, and how hard? | How much work is the SAP vendor sync? | A spike, a diagram, and an estimate range |
| Which option? | Invite-only accounts or self-registration? | A decision record with the options compared |
| Will it hold? | Can the approval queue handle 5,000 requests a day? | A load test on a throwaway build |
| What does it cost to run? | What does document scanning cost per supplier? | A cost estimate with its assumptions |
| What breaks? | What happens when SAP is down during approval? | A sequence diagram with the failure path |
Spikes
A spike is a time-boxed piece of work that answers one technical question. Its output is an answer, not production code.
- One question. Write it so it has an answer: "Can we create a vendor in SAP from our backend in under one second?" A spike called "look into SAP" never ends.
- A time box. Set it before you start, usually one to three days. When the time runs out, report what you know. An unfinished spike is still an answer: "not within three days" is information.
- A pass mark. Write which result means go, and which means change course, as for any assumption test.
- An owner. One engineer owns the answer, even when two people work on it.
- Throwaway code. Keep spike code on a branch, or delete it. Rebuild what survives with tests and review, through a change request.
Spikes on the roadmap
Put each spike on the Roadmap as an Enabling discovery goal. The kind says what the work is: it finds out what is true about what the product or the system needs. The roadmap draws it with a dashed border. When a delivery goal waits on the spike's answer, make the delivery goal depend on the spike, so the order is visible.
- 1Enabling discovery: the spike.
- 2Enabling delivery that depends on it.
- 3Product delivery that users see.
When the spike ends, link its evidence to the goal. In the goal's Links section, select Reference an artifact… or Reference a prototype…. See Roadmaps for goals and dependencies.
Diagrams
A diagram explains a system faster than prose when the question is about structure, order or state. Draw the diagram that answers the spike's question, not a picture of everything.
| Diagram | Answers |
|---|---|
| Context | Which systems and people are involved, and what crosses each boundary? |
| Sequence | In which order do calls happen, and where does a failure go? |
| State | Which states can a record be in, and which moves are allowed? |
| Data | Which entities exist, and how do they relate? |
In Roko Platform, a diagram is an artifact with the format Diagram. On the Artifacts page, select New artifact, then Blank diagram. The platform opens the draw.io editor inside the page and saves as you work.
You can also ask your agent to draw a diagram. The agent writes it over MCP with create_artifact and the format Diagram, and the platform gives it the draw.io XML reference it needs.
Create a Diagram artifact in the vendor-onboarding project: a sequence diagram of approving a supplier and creating the vendor in SAP. Show what happens when SAP times out.Documents
Platform artifacts also hold the written results of technical discovery. The New artifact dialog offers a Document (blank, or from a template), a Diagram, or Upload a file.
| Format | Use it for |
|---|---|
| Markdown | Spike write-ups, RFCs, decision records, research notes |
| Web page | A self-contained HTML page: a benchmark report with charts, or a small interactive explainer |
| Diagram | draw.io diagrams |
| File | Anything else you upload, such as a PDF from a vendor or a CSV of test results |
An agent creates a markdown or web page artifact with create_artifact. It changes an artifact with replace_artifact_body, which takes the version it read. If somebody changed the artifact in the meantime, the platform rejects the write, and the agent reads the artifact again. Team members comment on an artifact in the app.
RFCs and decision records
An RFC (request for comments) proposes a technical approach while the options are still open. A decision record states what the team chose, and why, after the options close. The platform has no separate object for either. Use these homes:
| Stage | Where it lives in the platform |
|---|---|
| Options still open | A markdown artifact. Reviewers comment on it. |
| Decided, for one change | The Decisions section of the change request that builds it |
| Decided, for the whole project | An entry in the Architecture document of the working model, added by a model change in a change request |
Keep an RFC short. A reader should finish it in ten minutes.
RFC: <title>
Question: <the one question this answers>
Context: <what forces a decision now; constraints; links to the spike write-up>
Options: A) ... B) ... C) ... (at least two, including "do nothing" if real)
Comparison: <table: cost, risk, reversibility, what each makes harder later>
Proposal: <the option you recommend, and why it beat the others>
Open: <what you still do not know, and how you would find out>A decision record carries three parts: the context, the decision, and the consequence. An Architecture entry must carry enough that a future reader can tell whether the choice still holds.
We use Postgres full-text search. The corpus is under a million rows, and we already run Postgres. It will not scale to fuzzy multilingual search. Revisit it then.
That entry beats "We use Postgres full-text search", because it names when to change it.
From spike to change request
Technical discovery ends in a decision, and the decision enters delivery through a change request.
- Diagram (draw.io)
- Web page or markdown notes
- Prototype, if the question is about a UI
Close the spike
Write the answer in a markdown artifact: the question, what you tried, the result against the pass mark, and what you still do not know. Link it, and any diagram, to the spike's goal as evidence.
Open the change request
Open a change request for the chosen option. Link the spike write-up in its text. Put the chosen option and the rejected ones in the Decisions section. You can also ask your agent to open the change request.
Update the working model
When the decision must hold beyond this change, add a model change to the same change request. Choose the document by what the spike taught:
The spike taught Working model document Why the system is built a certain way Architecture A new entity, rule or term Domain Model A step, a sequence or a failure path Flows A limit, a guardrail or a non-functional requirement Quality Plan Plan the delivery
Create or update the delivery goal that the spike unblocked, and link the change request to it.