Workflows ORVEN has no fixed layout. Each job gets the columns it needs. These are the boards engineers open most, with a full guide for each.
Debugging Find out why, with the evidence on one screen. 01 Chase a bug Open nvim, the Debugger and the dev server. Set a breakpoint, trigger the request, read the variables. The code, the paused frame and the server's output stay on screen together.
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
Debugger refund.ts:42
40 const prior = await db.refunds
41 .findOne({ key })
42 if (prior) return prior
43 const r = await stripe.refund(evt)
Variables
key : "rf_812_9c1e"
prior : null
evt.orderId : 812
Call stack
refund refund.ts:42
handleWebhook webhooks.ts:17
api pnpm dev
14:01:58.204 POST /webhooks/stripe 200
14:01:58.241 POST /webhooks/stripe 200
14:01:58.250 refund.created r_3301 order=812
14:01:58.262 refund.created r_3302 order=812
14:02:03.118 GET /orders/812 200 6ms
[watch] refund.ts changed
restarted in 298ms
14:06:41.002 GET /orders/812 200 5ms
14:06:44.517 POST /webhooks/stripe 200
14:06:44.530 POST /webhooks/stripe 409 dup key
02 Fix a flaky test Keep the test runner in watch mode next to the code. Every save reruns the test; the failure and the log that explains it stay visible.
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
test vitest --watch
✓ refund · returns prior refund
✓ refund · rejects unpaid order
✕ refund · concurrent webhooks refund once
✓ webhook · verifies signature
AssertionError: expected 1 refund, received 2
❯ refund.spec.ts:58:24
Tests 1 failed | 14 passed (15)
Duration 2.1s
waiting for file changes...
03 Investigate an incident Start from the logs, confirm in the data, and have the agent piece together what happened while you keep digging.
api pnpm dev
14:01:58.204 POST /webhooks/stripe 200
14:01:58.241 POST /webhooks/stripe 200
14:01:58.250 refund.created r_3301 order=812
14:01:58.262 refund.created r_3302 order=812
14:02:03.118 GET /orders/812 200 6ms
[watch] refund.ts changed
restarted in 298ms
14:06:41.002 GET /orders/812 200 5ms
14:06:44.517 POST /webhooks/stripe 200
14:06:44.530 POST /webhooks/stripe 409 dup key
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
Database payments_dev
orders refunds webhooks
select * from refundswhere order_id = 812
id amount created_at
r_3301 48.00 14:01:58.250
r_3302 48.00 14:01:58.262
Understanding code Get from "what is this" to "I can change it". 04 Read unfamiliar code Ask the agent how a path works. It answers with a diagram drawn from the source, its boxes pointing at the code they stand for.
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
05 Trace a request end to end Send one real request and follow it through the code. The log shows where it went, the agent maps it, nvim shows each stop.
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
api pnpm dev
14:01:58.204 POST /webhooks/stripe 200
14:01:58.241 POST /webhooks/stripe 200
14:01:58.250 refund.created r_3301 order=812
14:01:58.262 refund.created r_3302 order=812
14:02:03.118 GET /orders/812 200 6ms
[watch] refund.ts changed
restarted in 298ms
14:06:41.002 GET /orders/812 200 5ms
14:06:44.517 POST /webhooks/stripe 200
14:06:44.530 POST /webhooks/stripe 409 dup key
Data & schema Change data with the table in view. 06 Change the schema Write the migration in nvim, run it, and check the table in the next column. Ask the agent what else reads it before you merge.
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
Database payments_dev
orders refunds webhooks
select * from refundswhere order_id = 812
id amount created_at
r_3301 48.00 14:01:58.250
r_3302 48.00 14:01:58.262
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
07 Backfill data Run the backfill and watch both its output and the table it writes to. Stop it the moment the numbers look wrong.
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
Database payments_dev
orders refunds webhooks
select * from refundswhere order_id = 812
id amount created_at
r_3301 48.00 14:01:58.250
r_3302 48.00 14:01:58.262
api pnpm dev
14:01:58.204 POST /webhooks/stripe 200
14:01:58.241 POST /webhooks/stripe 200
14:01:58.250 refund.created r_3301 order=812
14:01:58.262 refund.created r_3302 order=812
14:02:03.118 GET /orders/812 200 6ms
[watch] refund.ts changed
restarted in 298ms
14:06:41.002 GET /orders/812 200 5ms
14:06:44.517 POST /webhooks/stripe 200
14:06:44.530 POST /webhooks/stripe 409 dup key
Frontend See the change as you make it. 08 Build the UI Save in nvim. The page updates beside it. The dev server log is one glance away when something breaks.
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
Browser localhost:5173
localhost:5173/orders/812 Order #812 $48.00 · Paid
Refund r_3301 -$48.00
Refund r_3302 -$48.00
Issue refund
api pnpm dev
14:01:58.204 POST /webhooks/stripe 200
14:01:58.241 POST /webhooks/stripe 200
14:01:58.250 refund.created r_3301 order=812
14:01:58.262 refund.created r_3302 order=812
14:02:03.118 GET /orders/812 200 6ms
[watch] refund.ts changed
restarted in 298ms
14:06:41.002 GET /orders/812 200 5ms
14:06:44.517 POST /webhooks/stripe 200
14:06:44.530 POST /webhooks/stripe 409 dup key
09 Fix a visual regression The page looks wrong since the last merge. Put it beside an agent that finds the change, and review its fix before you commit it.
Browser localhost:5173
localhost:5173/orders/812 Order #812 $48.00 · Paid
Refund r_3301 -$48.00
Refund r_3302 -$48.00
Issue refund
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
Review fix/refund-once
0042_refund_key.sql +2
refund.ts +6 -3
refund.spec.ts +18
@@ -40,6 +40,9 @@
const prior = await db.refunds
- .findOne({ key })
+ .findOne({ key }, { lock: true })
if (prior) return prior
+ // unique index enforces once
const r = await stripe.refund(evt)
Working with agents Hand off a task. Stay in control of what lands. 10 Hand off a task Give the agent a scoped task and keep its changes and the test run open next to it. It asks before it writes.
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
Review fix/refund-once
0042_refund_key.sql +2
refund.ts +6 -3
refund.spec.ts +18
@@ -40,6 +40,9 @@
const prior = await db.refunds
- .findOne({ key })
+ .findOne({ key }, { lock: true })
if (prior) return prior
+ // unique index enforces once
const r = await stripe.refund(evt)
test vitest --watch
✓ refund · returns prior refund
✓ refund · rejects unpaid order
✕ refund · concurrent webhooks refund once
✓ webhook · verifies signature
AssertionError: expected 1 refund, received 2
❯ refund.spec.ts:58:24
Tests 1 failed | 14 passed (15)
Duration 2.1s
waiting for file changes...
11 Review agent changes Read what the agent wrote the way you read a teammate's PR. Comment on the lines, hand the comments back, and watch it revise.
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
Review fix/refund-once
0042_refund_key.sql +2
refund.ts +6 -3
refund.spec.ts +18
@@ -40,6 +40,9 @@
const prior = await db.refunds
- .findOne({ key })
+ .findOne({ key }, { lock: true })
if (prior) return prior
+ // unique index enforces once
const r = await stripe.refund(evt)
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
12 Run agents side by side Give two agents two tasks in one repository, each in a worktree of its own, each with its changes in view.
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
Review fix/refund-once
0042_refund_key.sql +2
refund.ts +6 -3
refund.spec.ts +18
@@ -40,6 +40,9 @@
const prior = await db.refunds
- .findOne({ key })
+ .findOne({ key }, { lock: true })
if (prior) return prior
+ // unique index enforces once
const r = await stripe.refund(evt)
13 Juggle several tasks A task on every board, agents working on all of them, and one key to whatever needs you next.
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
nvim refund.ts
36 import { db } from '../db'
37
38 export async function refund (evt) {
39 const key = evt.idempotencyKey
40 const prior = await db.refunds
41 .findOne ({ key })
42 i f (prior) return prior
43 const r = await stripe.refund (evt)
44 await db.refunds.insert ({ key, ...r })
45 return r
46 }
~
~
~
NORMAL payments/refund.ts 42:3
test vitest --watch
✓ refund · returns prior refund
✓ refund · rejects unpaid order
✕ refund · concurrent webhooks refund once
✓ webhook · verifies signature
AssertionError: expected 1 refund, received 2
❯ refund.spec.ts:58:24
Tests 1 failed | 14 passed (15)
Duration 2.1s
waiting for file changes...
Shipping Get it reviewed, merged and verified. 14 Ship it Last look at the changes, a full test run, and the deploy log, on one board until it is live.
Agent explain refund flow
How does a refund get from Stripe to the database?
Four hops. Nothing locks between the read and the insert, so a retried webhook can refund twice.
Stripe webhook
handleWebhook webhooks.ts:17
findOne no lock refund.ts:40
refunds.insert refund.ts:44
Review fix/refund-once
0042_refund_key.sql +2
refund.ts +6 -3
refund.spec.ts +18
@@ -40,6 +40,9 @@
const prior = await db.refunds
- .findOne({ key })
+ .findOne({ key }, { lock: true })
if (prior) return prior
+ // unique index enforces once
const r = await stripe.refund(evt)
test vitest --watch
✓ refund · returns prior refund
✓ refund · rejects unpaid order
✕ refund · concurrent webhooks refund once
✓ webhook · verifies signature
AssertionError: expected 1 refund, received 2
❯ refund.spec.ts:58:24
Tests 1 failed | 14 passed (15)
Duration 2.1s
waiting for file changes...