Change requests

Purpose

Teams that let work start from a chat message rebuild the same decision several times. Each person, and each agent, fills the gaps with a different guess. A written proposal that someone else reviews before anyone builds it removes most of those guesses. It also leaves a record of what the team agreed and why.

In Roko Platform, that proposal is a change request. A change request is a proposed change to the product. When the change also modifies the working model, the change request says so in its model changes. It carries two kinds of content:

• Spec sections describe how to build the change, in enough detail that an engineer or an agent can build it without asking questions.
• Model changes edit one or more working model documents. They carry the why and the principles.

Some change requests change only the working model and write no code. They are rarer than the others, and they are more common early in a project, while the team still sets its goals, users, and principles.

Every change request carries a Summary.

Each project numbers its change requests on their own, as CR-1, CR-2, and so on. The list is in the sidebar under Blueprint, as Change requests. The detail page has three tabs: Conversation, Spec, and Model Changes.

Spec sections

A spec is a set of named sections. Each section has one job and one format. Be concise, and use only the sections you need to resolve ambiguity. A change request holds at most one section of each kind, in this order:

Only the Summary is required. The platform refuses to move a change request out of Draft without one.

Write each fact once, in the section it belongs to. A fact written twice will disagree with itself after one edit. Prefer tables and bullets to paragraphs.

Model changes

A model change holds the full proposed body of one working model document. The Model Changes tab shows each one as a diff against the current document. The platform writes the documents only when the change request completes. How the working model changes covers the merge and the rebase.

Sections and model changes can be edited only while the change request is in Draft or In review.

Review

Reviewers give their verdict in the composer on the Conversation tab:

• The author cannot Accept or Block their own change request. A project with one member is exempt.
• Reviewers cannot give a verdict on a Draft, and verdicts are frozen once the change request leaves review.
• A Block stands until the same reviewer posts a newer verdict.
• An agent reviewer can also read the change request against the working model. Press Review this, or Review again after a change.

Review rules

Each project sets two rules under Settings → Project, in the Review rules section:

Lifecycle

1. Draft

   The author is still writing. Reviewers cannot give a verdict yet.

   Ready for review Needs a Summary.

2. In review

   Members comment, Accept, or Block. Sections and model changes stay editable.

   Start an implementation No Block may stand. Under the Needs review rule, it also needs one Accept from someone other than the author.

3. In implementation

   The spec and model changes are frozen. One or more implementations build it.

   Mark complete Every implementation must be settled first.

4. Complete

   The platform merges the model changes into the working model.

Shortcut

A change request with model changes and no code sections can go from In review to Complete with Merge model changes.

Side exit

Closed ends a change request without completing it.

No way back

Once an implementation starts, the change request cannot return to review. Close it and open a new one.

The list page also has an Implemented tab. The code defines that status for a change request whose completion hit a merge conflict, but this page could not confirm what sets it today.

Some rules follow from the lifecycle:

• An implementation cannot start from Draft, while a Block stands, or, under Needs review, before an Accept.
• A change request cannot go back to review once an implementation has started. If the spec turns out to be wrong, close it and open a new one.
• Mark complete is disabled while any implementation is still active. Every linked implementation must be settled first.
• Merging pull requests does not complete the change request. Implementations explains what completes on its own and what a person does.

Threads and comments

A thread is a discussion on a change request. It has one of three anchors:

• The conversation. The thread sits on the Conversation tab.
• A spec section. The thread anchors to a range of lines in one section.
• A model change. The thread anchors to a range of lines on the old or new side of the diff.

Anchored threads can be opened only in Draft or In review. Replies, edits, and Resolve work at every status. Nobody can reply to a resolved thread until someone presses Unresolve. Only a comment's author can edit it.

Opening one with an agent

The New change request button on the Change requests page does not open a form. It gives you a prompt to copy. Paste the prompt into your coding agent, and replace the line in angle brackets with what you want to change and why. The agent then interviews you until no ambiguity remains, and only then writes the change request:

1. It asks what you want and why

   It plays your answer back to you in a sentence or two, and it keeps asking until the intent is clear. Then it tells you whether the change needs a model change, spec sections, or both, and you can correct it.

2. It reads before it asks

   It reads the working model documents that the change touches, the change requests in flight, and the code when the change needs it. It settles every fact it can from that evidence, and it asks you only what the evidence cannot answer.

3. It asks one question at a time

   Each question comes with a recommended answer and the evidence behind it. The agent restates each decision in the project's vocabulary and records it in a draft under ./cr-drafts/ before it asks the next question. Each model change and each spec section has its own file.

4. It checks the drafts as a whole

   When no question remains, the agent reads the drafts for decisions that conflict, questions that nobody answered, terms without a definition, and claims without evidence. It takes each one back to you as a new question.

5. It creates the change request after you approve

   You read the drafts and ask for changes. The agent revises them until you approve, then creates the change request with create_change_request. The change request starts In review.

Expect many questions. The agent creates nothing before you approve the drafts. Connect over MCP sets up the MCP connection that the agent needs.

Best practices

• Be concise. Use only the sections that resolve ambiguity. A section that restates another adds reading and no information.
• Numbers, not adjectives. "p95 under 200 ms" is testable. "Fast" is not.
• Record decisions with their reasons. A decision without the alternative it beat is a guess.
• State what you do not know. An open question is a Decisions row marked "assumed until X", with an owner.
• Resolve threads before you implement. Implementers read the threads, and an open thread often holds a decision the spec missed.
• Do not change the plan on the branch. If the spec is wrong, open a new change request.