Code Flow Analysis Protocol

Trace execution paths before implementing. Understand the flow, then fix.

Core Principle

Map the execution path before changing code. When fixing bugs, implementing features, or refactoring, you must first understand how the code currently flows through your fn(args, deps) functions, Result types, and workflows.

When This Activates

Before:

• Fixing bugs
• Implementing features
• Refactoring
• Starting TDD cycles
• Debugging issues

Skip for: Typos, formatting, documentation-only changes.

The Protocol (3 Steps)

1. Trace the Execution Path

Answer these with file:line references:

• Entry point: Which HTTP handler/queue consumer/CLI command triggers this? (src/api/routes.ts:45)
• Function chain: Which fn(args, deps) functions are called? (src/domain/get-user.ts:12)
• Workflow composition: Does it use createWorkflow()? Which steps? (src/workflows/load-user-data.ts:23)
• Error location: Where does the failure occur? (src/domain/get-user.ts:28)
• Result flow: How does the Result propagate? (src/api/handlers.ts:67)

2. Create Execution Diagram

Show the flow with Result types and deps:

HTTP Request: POST /users/:id
  ↓ (args: { userId: string })
Handler.getUser() [src/api/handlers.ts:45]
  ↓ (validates with Zod schema)
getUserSchema.safeParse() [src/api/handlers.ts:48]
  ↓ (parsed.data: { userId: string })
getUser(args, deps) [src/domain/get-user.ts:12]
  ↓ (deps: { db: Database, logger: Logger })
deps.db.findUser() [src/infra/database.ts:89]
  ↓ (returns: User | null)
Result check [src/domain/get-user.ts:28]
  ↓ (if null) → err('NOT_FOUND')
  ↓ (if user) → ok(user)
resultToResponse() [src/api/handlers.ts:67]
  ↓ (maps Result → HTTP)
HTTP 200 or 404

Key elements:

• Show fn(args, deps) signatures
• Show Result types (ok() vs err())
• Show workflow steps if applicable
• Mark error location with 💥
• Keep it concise (5-15 lines max)

3. Verify Understanding

Ask: "Here's the execution flow: [diagram]. The error occurs at [file:line] when [condition]. Correct?"

Wait for confirmation before proceeding.

Integration with Patterns

fn(args, deps) Pattern

When tracing, identify:

• Which functions receive which args
• Which deps are injected at each step
• Where dependencies are wired (composition root)

// Trace shows:
getUser(args: { userId }, deps: { db, logger })
  ↓
createUser(args: { name, email }, deps: { db, logger, mailer })
  ↓
// Question: Why does createUser need mailer but getUser doesn't?
// Answer: Each function declares only what it uses (per fn-args-deps)

Result Types

Show Result propagation:

getUser() → Result<User, 'NOT_FOUND' | 'DB_ERROR'>
  ↓
createWorkflow({ getUser })
  ↓
step(() => getUser(...)) → unwraps Result
  ↓
if err → short-circuits, returns err
if ok → continues to next step

Workflow Composition

Trace through createWorkflow():

workflow(async (step) => {
  const user = await step(() => getUser(...));      // Step 1
  const posts = await step(() => getPosts(...));    // Step 2 (skipped if Step 1 err)
  return { user, posts };                           // Only if all ok
})

Example: Bug Fix

Problem: getUser returns err('DB_ERROR') but database is working.

❌ WRONG (guessing): "I'll add retry logic to getUser."

✅ RIGHT (tracing first):

1. Trace:

   • Entry: GET /users/:id → Handler.getUser [src/api/handlers.ts:45]
   • Calls: getUser(args, deps) [src/domain/get-user.ts:12]
   • Error: catch block returns err('DB_ERROR') [src/domain/get-user.ts:28]
   • But: deps.db.findUser is mocked in tests, real DB in integration

2. Diagram:

   Handler.getUser() [src/api/handlers.ts:45]
     ↓
   getUser(args, deps) [src/domain/get-user.ts:12]
     ↓
   deps.db.findUser() [src/infra/database.ts:89]
     ↓ (throws Error)
   catch block [src/domain/get-user.ts:28] ← 💥 Returns err('DB_ERROR')
     ↓
   But: Error message is "Connection timeout", not "Connection refused"
   

3. Verify: "The error occurs in the catch block, but the actual error is a timeout, not a connection failure. The function is catching all errors as 'DB_ERROR'. Should we distinguish timeout vs connection errors?"

Now the fix is clear: Add specific error handling for timeout vs connection errors, or add timeout to the workflow level (per resilience patterns).

Example: Feature Implementation

Request: "Add email validation to user creation."

❌ WRONG: "I'll add validation inside createUser function."

✅ RIGHT:

1. Trace current flow:

   POST /users
     ↓
   Handler.createUser() [src/api/handlers.ts:67]
     ↓
   createUserSchema.safeParse() [src/api/handlers.ts:70] ← Validation happens here
     ↓
   createUser(args, deps) [src/domain/create-user.ts:15]
     ↓
   deps.db.saveUser() [src/infra/database.ts:102]
   

2. Diagram shows: Validation already happens at boundary (per validation-boundary pattern).

3. Verify: "Email validation should be in the Zod schema at the boundary, not inside createUser. The schema is at [file:line]. Should I add email validation there?"

Rules

1. Always trace before implementing - No exceptions for non-trivial changes
2. Use file:line references - Not abstractions like "the handler" or "some function"
3. Show Result flow - How errors propagate through the system
4. Show deps injection - Where dependencies come from
5. Get confirmation - Don't proceed without user verification
6. Keep diagrams concise - 5-15 lines, focus on the relevant path

Anti-Patterns

❌ "I'll fix the validation error" (didn't trace where it occurs) ✅ "Let me trace where validation fails... [diagram]. The error is at [file:line] when [condition]. Correct?"

❌ "I'll add retry logic" (didn't check if retry exists at workflow level) ✅ "Tracing the flow... [diagram]. Retry should be at workflow level per resilience patterns, not inside the function. Correct?"

Integration with Other Skills

• debugging-methodology: Use this protocol BEFORE adding instrumentation
• tdd-workflow: Use this to understand what to test in RED phase
• result-types: Always show Result propagation in diagrams
• resilience: Identify where retry/timeout should be added (workflow level)

Quick Reference

Remember: Understanding the flow makes the solution obvious. Guessing wastes time.