How to trace an auth flow with agentmako

The bug report

You get a Linear ticket: "Onboarding for managers is broken. Some new managers see a 403 on /api/manager/onboarding but other managers in the same district can complete the flow."

You don't know this part of the code well. The agent doesn't know it at all.

The vanilla approach (and why it falls over)

Without agentmako, the agent's first ten moves look like:

$ rg -n "manager onboarding" .
$ rg -n "/api/manager" app/
$ ls app/api/manager
$ cat app/api/manager/onboarding/route.ts
$ rg -n "role" lib/auth/
$ cat lib/auth/dal.ts
$ cat lib/auth/roles.ts
$ rg -n "district" lib/
... etc.

That's 5,000+ tokens of grep output and file reads before the agent has a hypothesis. Worse, it has no idea whether admin_audit_log, manager_district, or onboarding_state are RLS-sensitive — so even if it finds the role check, it'll miss the row-level-security policy that's actually blocking some managers.

The agentmako approach

Four targeted tool calls instead of grep loops.

Step 1 — `auth_path`

Ask "what's the auth boundary on this route?" before reading any code.

{
  "tool": "auth_path",
  "args": {
    "route": "/api/manager/onboarding",
    "verb": "POST"
  }
}

Returns the route → likely auth-guard files → verifySession/requireRole call sites → relevant tables. You now know that the role check lives in lib/auth/dal.ts:resolveManagerScope and the data access is in app/api/manager/onboarding/route.ts.

Step 2 — `route_trace`

{
  "tool": "route_trace",
  "args": { "route": "/api/manager/onboarding", "verb": "POST" }
}

Returns the resolved handler file, the imports it pulls in, the Supabase tables it touches via .from(), and any related routes. You learn the handler reads manager_district and writes onboarding_state.

Step 3 — `db_rls` on the touched tables

{
  "tool": "db_rls",
  "args": { "schema": "public", "table": "manager_district" }
}

Returns RLS state and policy bodies. Here's where the bug usually hides: a policy that checks auth.uid() = user_id when it should check auth.uid() IN (SELECT manager_id FROM district_managers WHERE district_id = manager_district.district_id).

Step 4 — `file_findings` before editing

{
  "tool": "file_findings",
  "args": { "filePath": "lib/auth/dal.ts", "limit": 20 }
}

Reef returns existing findings on this file. Maybe someone has already noted "missing tenant scope on resolveManagerScope" with an explanation. Don't redo that analysis — read it.

Optional — `reef_inspect`

{
  "tool": "reef_inspect",
  "args": { "subjectKind": "file", "subjectId": "lib/auth/dal.ts" }
}

Full evidence trail: facts, findings, recent diagnostic runs, and any acks. If there's an ack saying "we know this looks weird, it's intentional because X" — read that before changing the code.

The fix

Now the agent has the context it needs to actually edit. The route handler doesn't call resolveManagerScope before the database read; the RLS policy on manager_district is correct but the handler is querying with the user's session role rather than the resolved manager scope. One-line fix in the handler.

Total tool calls: 4-5. Total tokens of context: roughly 1,200. Compare to the vanilla path: 12,000+ tokens before any hypothesis.

Variations

Cross-tenant audit: swap db_rls for tenant_leak_audit when you suspect the bug is systemic across tenant-keyed tables.
Frontend-only auth bug: start with route_context instead of auth_path — it returns the surrounding layout, middleware, and client/server boundary checks.
Pre-commit gate: after the fix, run git_precommit_check to catch any boundary regressions in the staged diff.

Tools used in this recipe

auth_path — trace likely auth boundaries for a route, file, or feature.
route_trace — trace a route to its handler, files, and nearby evidence.
route_context — return route resolution and route neighborhood.
db_rls — RLS enabled state and policies for one table.
file_findings — durable findings for a specific file before editing it.
reef_inspect — full evidence trail for one file or subject.
tenant_leak_audit — multi-tenant RLS posture audit.
git_precommit_check — staged TS/TSX route auth and boundary checks.

The bug report

The vanilla approach (and why it falls over)

The agentmako approach

Step 1 — auth_path

Step 2 — route_trace

Step 3 — db_rls on the touched tables

Step 4 — file_findings before editing

Optional — reef_inspect