Chapter 01 / 08

Capture and decide

Preserve the observation, decide the direction, and give the work a clear boundary.

Begin with what happened

Velocity starts a work item at Capture: record the observation and the evidence. Preserve the person’s account of the problem. Keep the observed behavior separate from a possible explanation, and name what you still do not know.

This matters when a coding agent can move from a plausible diagnosis to a patch in one turn. A precise account gives the next role something stable to investigate and gives acceptance a behavior to replay.

Make the decision visible

Decision is where the appropriate owner chooses the product, architecture, lane, or priority direction. The agent can surface evidence and options. The owner resolves a consequential ambiguity: should a preference belong to this device, this session, or the account across devices?

That decision changes both implementation and acceptance. Put it in the project’s authoritative record before treating one interpretation as the requirement. Velocity uses existing issue and decision records; the project chooses its storage and tools.

Preserve architecture decisions

When the choice changes a durable contract, ownership, or a trust boundary, use Architect review and preserve the decision in an ADR. Record its context, alternatives, rationale, acceptance, consequences, and the mechanisms enforcing its invariants. Link a superseding decision when the context changes. Read the ADR discipline guidance.

Turn the decision into a tranche

A tranche is a bounded piece of work with acceptance criteria and a proof gate. Name the outcome, what is included, the working lane, and the evidence needed to close it. Separate architecture decisions or live deployment when they require different authority.

For the list example, a local implementation tranche might repair preference persistence and replay the reported sequence in a local runtime. Its closeout should state that lane. Evidence from a local session cannot establish what a deployed production build does.

Try it on your next issue

1. Write the reported start state, action, observed result, and expected result.
2. Label suspected causes as hypotheses and record missing evidence.
3. Ask the appropriate owner to resolve product or architecture decisions.
4. Use a tranche to bind the accepted scope to an observable finish line.