Agent skill

Trace and Isolate

Techniques for tracing code execution and isolating problematic components

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/trace-and-isolate

SKILL.md

Trace and Isolate

You are using systematic tracing and isolation techniques to narrow down where a bug originates. The goal is to find the exact location in code where behavior diverges from expectation.

Core Principle

Divide and conquer. Systematically narrow the search space until you find the exact point of failure.

Binary Search Debugging

When you have a large codebase or complex flow:

  1. Identify the start - Last known good state
  2. Identify the end - First observed bad state
  3. Test the middle - Check if behavior is good or bad
  4. Repeat - Binary search on the half with the bug

Code Path Binary Search

Start: User clicks submit button
End: Error shown to user

Midpoint 1: Form validation
→ Data looks correct here? Continue to later code
→ Data already wrong? Focus on earlier code

Midpoint 2: API request construction
→ Request payload correct? Focus on server side
→ Payload already malformed? Focus on form handling

...Continue until exact line is found

Git Bisect for Regressions

When a bug appeared between two commits:

bash
# Start bisect
git bisect start

# Mark current (broken) state as bad
git bisect bad

# Mark last known good state
git bisect good v2.3.0

# Git checks out middle commit, test and mark
git bisect good  # or git bisect bad

# Repeat until found
# Git will report: "abc123 is the first bad commit"

# Clean up
git bisect reset

Automated bisect with test script:

bash
git bisect start HEAD v2.3.0
git bisect run npm test -- --grep "failing test"

Tracing Techniques

Strategic Logging

Add temporary logging at key points:

typescript
function processOrder(order) {
  console.log('[TRACE] processOrder input:', JSON.stringify(order));

  const validated = validateOrder(order);
  console.log('[TRACE] after validation:', JSON.stringify(validated));

  const priced = calculatePrice(validated);
  console.log('[TRACE] after pricing:', JSON.stringify(priced));

  const result = submitOrder(priced);
  console.log('[TRACE] final result:', JSON.stringify(result));

  return result;
}

Log template: [TRACE] <location>: <what> = <value>

Data Flow Tracing

Track how data transforms through the system:

Input: { userId: "123", items: [...] }
    ↓
validateUser() → { userId: "123", verified: true }
    ↓
enrichItems() → { userId: "123", verified: true, items: [...enriched] }
    ↓
calculateTotals() → { ..., subtotal: 100, tax: 8, total: 108 }
    ↓
Output: { orderId: "456", total: 108 }

At each step, verify:

  • Is the input what you expected?
  • Is the output what you expected?
  • Where does expected diverge from actual?

Control Flow Tracing

Track which code paths execute:

typescript
function handleRequest(req) {
  console.log('[TRACE] handleRequest entered');

  if (req.authenticated) {
    console.log('[TRACE] authenticated path');
    if (req.isAdmin) {
      console.log('[TRACE] admin path');
      return handleAdminRequest(req);
    } else {
      console.log('[TRACE] user path');
      return handleUserRequest(req);
    }
  } else {
    console.log('[TRACE] unauthenticated path');
    return handlePublicRequest(req);
  }
}

Isolation Techniques

Component Isolation

Test components in isolation to determine which is faulty:

Full System: Frontend → API → Database
              ↓
Test 1: Frontend → Mock API
        → Works? Problem is in API or Database

Test 2: Real API → Mock Database
        → Works? Problem is in Database

Test 3: API with minimal data
        → Works? Problem is data-dependent

Minimal Reproduction

Strip away everything non-essential:

  1. Remove unrelated code - Comment out or delete
  2. Simplify data - Use minimal test data
  3. Remove dependencies - Mock external services
  4. Reduce scope - Single function/component

Goal: Smallest possible code that still shows the bug

Environment Isolation

Eliminate environmental factors:

  • Same behavior in different browsers?
  • Same behavior on different machines?
  • Same behavior with fresh data?
  • Same behavior after clearing cache?
  • Same behavior with default config?

Breakpoint Strategies

Strategic Breakpoint Placement

typescript
function complexFunction(input) {
  // BREAKPOINT 1: Entry - check input
  const step1 = transform(input);
  // BREAKPOINT 2: After first transformation

  for (const item of step1.items) {
    // BREAKPOINT 3: Inside loop - conditional on item
    process(item);
  }

  // BREAKPOINT 4: Exit - check output
  return finalize(step1);
}

Conditional Breakpoints

Only break when condition is met:

  • item.id === "problematic-id"
  • count > 100
  • response.status !== 200

Watch Expressions

Monitor values without stopping:

  • this.state.items.length
  • performance.now() - startTime
  • Object.keys(cache).length

Isolation Checklist

Before declaring a component faulty:

  • Tested in complete isolation?
  • All inputs verified correct?
  • All dependencies mocked/verified?
  • Tested with known-good data?
  • Reproduced on clean environment?

Common Isolation Patterns

Database Isolation

sql
-- Create isolated test data
BEGIN TRANSACTION;
-- Insert test data
-- Run test queries
-- Verify results
ROLLBACK;

Network Isolation

typescript
// Intercept and log all network requests
const originalFetch = window.fetch;
window.fetch = async (...args) => {
  console.log('[TRACE] fetch:', args[0]);
  const response = await originalFetch(...args);
  console.log('[TRACE] response:', response.status);
  return response;
};

Time Isolation

typescript
// Control time for debugging
const realNow = Date.now;
Date.now = () => {
  const time = realNow();
  console.log('[TRACE] Date.now():', new Date(time).toISOString());
  return time;
};

When to Move On

Stop isolating when you have:

  • Exact file and line number
  • Minimal reproduction case
  • Clear understanding of trigger conditions
  • Evidence for root cause hypothesis

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results