trace-and-isolate
Applies systematic tracing and isolation techniques to pinpoint exactly where a bug originates in code. Use when a bug is hard to locate, code is not working as expected, an error or crash appears with unclear cause, a regression was introduced between recent commits, or you need to narrow down which component, function, or line is faulty. Covers binary search debugging, git bisect for regressions, strategic logging with [TRACE] patterns, data and control flow tracing, component isolation, minimal reproduction cases, conditional breakpoints, and watch expressions across TypeScript, SQL, and bash.
Best use case
trace-and-isolate is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Applies systematic tracing and isolation techniques to pinpoint exactly where a bug originates in code. Use when a bug is hard to locate, code is not working as expected, an error or crash appears with unclear cause, a regression was introduced between recent commits, or you need to narrow down which component, function, or line is faulty. Covers binary search debugging, git bisect for regressions, strategic logging with [TRACE] patterns, data and control flow tracing, component isolation, minimal reproduction cases, conditional breakpoints, and watch expressions across TypeScript, SQL, and bash.
Teams using trace-and-isolate should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/trace-and-isolate/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How trace-and-isolate Compares
| Feature / Agent | trace-and-isolate | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Applies systematic tracing and isolation techniques to pinpoint exactly where a bug originates in code. Use when a bug is hard to locate, code is not working as expected, an error or crash appears with unclear cause, a regression was introduced between recent commits, or you need to narrow down which component, function, or line is faulty. Covers binary search debugging, git bisect for regressions, strategic logging with [TRACE] patterns, data and control flow tracing, component isolation, minimal reproduction cases, conditional breakpoints, and watch expressions across TypeScript, SQL, and bash.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
# 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.
## Quick Reference
| Scenario | Technique |
|---|---|
| Large codebase / complex flow | Binary search debugging |
| Bug appeared between commits | `git bisect` |
| Unclear data transformation | Strategic `[TRACE]` logging |
| Which component is faulty? | Component isolation + mocks |
| Bug hard to reproduce | Minimal reproduction case |
| Conditional or intermittent bug | Conditional breakpoints / watch expressions |
## 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 hypothesisRelated Skills
find-skills
Discovers, searches, and installs skills from multiple AI agent skill marketplaces (400K+ skills) using the SkillKit CLI. Supports browsing official partner collections (Anthropic, Vercel, Supabase, Stripe, and more) and community repositories, searching by domain or technology, and installing specific skills from GitHub. Use when the user wants to find, browse, or install new agent skills, plugins, extensions, or add-ons; asks 'is there a skill for X' or 'find a skill for X'; wants to explore a skill store or marketplace; needs to extend agent capabilities in areas like React, testing, DevOps, security, or APIs; or says 'browse skills', 'search skill marketplace', 'install a skill', or 'what skills are available'.
test-patterns
Applies proven testing patterns — Arrange-Act-Assert (AAA), Given-When-Then, Test Data Builders, Object Mother, parameterized tests, fixtures, spies, and test doubles — to help write maintainable, reliable, and readable test suites. Use when the user asks about writing unit tests, integration tests, or end-to-end tests; structuring test cases or test suites; applying TDD or BDD practices; working with mocks, stubs, spies, or fakes; improving test coverage or reducing flakiness; or needs guidance on test organization, naming conventions, or assertions in frameworks like Jest, Vitest, pytest, or similar.
red-green-refactor
Guides the red-green-refactor TDD workflow: write a failing test first, implement the minimum code to make it pass, then refactor while keeping tests green. Use when a user asks to practice TDD, write tests first, follow red-green-refactor, do test-driven development, write failing tests before code, or phrases like 'make the test pass', 'test coverage', or 'unit tests before implementation'.
testing-anti-patterns
Reviews test code to identify and fix common testing anti-patterns including flaky tests, over-mocking, brittle assertions, test interdependency, and hidden test logic. Flags bad patterns, explains the specific defect, and provides corrected implementations. Use when reviewing test code, debugging intermittent or unreliable test failures, or when the user mentions flaky tests, test smells, brittle tests, test isolation issues, mock overuse, slow tests, or test maintenance problems.
verification-gates
Creates explicit validation checkpoints (verification gates) between project phases to catch errors early and ensure quality before proceeding. Use when the user asks about quality gates, milestone checks, phase transitions, approval steps, go/no-go decision points, or preventing cascading errors across a multi-step workflow. Produces acceptance criteria checklists, automated CI gate configurations, manual sign-off requirements, and conditional review rules for scenarios such as security changes, API changes, or database migrations.
task-decomposition
Breaks down complex software, writing, or research tasks into small, atomic, independently completable units with dependency graphs and milestone breakdowns. Use when the user asks to plan a project, decompose a feature, create subtasks, split up work, or needs help organizing a large piece of work into a step-by-step plan. Triggered by phrases like "break down", "decompose", "where do I start", "too big", "split into tasks", "work breakdown", or "task list".
design-first
Guides the creation of technical design documents before writing code, producing architecture diagrams, data models, API interface definitions, implementation plans, and multi-option trade-off analyses. Use when the user asks to plan a feature, architect a system, design an API, explore implementation approaches, or requests a technical design or spec before coding — especially for complex features involving multiple components, ambiguous requirements, or significant architectural changes.
skill-authoring
Creates and structures SKILL.md files for AI coding agents, including YAML frontmatter, trigger phrases, directive instructions, decision trees, code examples, and verification checklists. Use when the user asks to write a new skill, create a skill file, author agent capabilities, generate skill documentation, or define a skill template for Claude Code agents.
root-cause-analysis
Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate why something is not working; especially for complex or intermittent issues across multiple components. Applies the Five Whys method, hypothesis-driven testing, stack trace analysis, git blame/log evidence gathering, and causal chain documentation to isolate and confirm root causes before applying any fix.
hypothesis-testing
Applies the scientific method to debugging by helping users form specific, testable hypotheses, design targeted experiments, and systematically confirm or reject theories to find root causes. Use when a user says their code isn't working, they're getting an error, something broke, they want to troubleshoot a bug, or they're trying to figure out what's causing an issue. Concrete actions include isolating failing components, forming and testing hypotheses, analyzing error messages, tracing execution paths, and interpreting test results to narrow down root causes.
structured-code-review
Performs a structured five-stage code review covering requirements compliance, correctness, code quality, testing, and security/performance. Each stage uses targeted checklists and categorized feedback (Blocker/Major/Minor/Nit) with actionable suggestions and rationale. Use when the user asks for code review, PR feedback, pull request review, or wants their code checked for bugs, style issues, or vulnerabilities — triggered by phrases like "review my code", "check this PR", "review my changes", "pull request review", or "code feedback".
parallel-investigation
Coordinates parallel investigation threads to simultaneously explore multiple hypotheses or root causes across different system areas. Use when debugging production incidents, slow API performance, multi-system integration failures, or complex bugs where the root cause is unclear and multiple plausible theories exist; when serial troubleshooting is too slow; or when multiple investigators can divide root-cause analysis work. Provides structured phases for problem decomposition, thread assignment, sync points with Continue/Pivot/Converge decisions, and final report synthesis.