# root-cause-tracing

Systematically traces bugs backward through the call stack to identify where invalid data or incorrect behavior originates.

* Purpose - Find the source of bugs that manifest deep in execution
* Output - Trace chain from symptom to original trigger with fix recommendation

```bash
/root-cause-tracing
```

## Arguments

None. The command works with the current bug context from your conversation.

## How It Works

1. **Observe Symptom**: Identify where the error appears (e.g., wrong file created, incorrect output)
2. **Find Immediate Cause**: Locate the code that directly causes the error
3. **Trace Upward**: Ask "what called this?" and follow the chain
4. **Track Values**: Note what values were passed at each level
5. **Find Origin**: Continue until you find where invalid data originated
6. **Add Instrumentation**: If manual tracing fails, add stack trace logging
7. **Fix at Source**: Address the root trigger, not the symptom location

### Key Principle

Never fix just where the error appears. Trace back to find the original trigger.

## Usage Examples

```bash
# After encountering a deep stack error
> /root-cause-tracing

# When debugging file creation in wrong location
> /root-cause-tracing
```

### Example Trace

```
Symptom: .git created in packages/core/ (source code)

Trace chain:
1. git init runs in process.cwd() <- empty cwd parameter
2. WorktreeManager called with empty projectDir
3. Session.create() passed empty string
4. Test accessed context.tempDir before beforeEach
5. setupCoreTest() returns { tempDir: '' } initially

Root cause: Top-level variable initialization accessing empty value
Fix: Made tempDir a getter that throws if accessed before beforeEach

Defense-in-depth added:
- Layer 1: Project.create() validates directory
- Layer 2: WorkspaceManager validates not empty
- Layer 3: NODE_ENV guard refuses git init outside tmpdir
- Layer 4: Stack trace logging before git init
```

## Best practices

* Use console.error in tests - Loggers may be suppressed in test environments
* Log before dangerous operations - Capture state before failure, not after
* Include full context - Directory, cwd, environment variables, timestamps
* Add defense-in-depth - Fix at source AND add validation at each layer
* Capture stack traces - Use `new Error().stack` for complete call chains


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cek.neolab.finance/plugins/kaizen/root-cause-tracing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.