From 781dbc8ae40066c0ee9788487b69ba1e4c46b7ac Mon Sep 17 00:00:00 2001 From: Steven Bouwkamp Date: Wed, 17 Dec 2025 10:04:18 -0500 Subject: [PATCH 1/2] Add /analyze-crash and /analyze-error --- .claude/commands/analyze-crash.md | 201 ++++++++++++++++++++++ .claude/commands/analyze-error.md | 276 ++++++++++++++++++++++++++++++ 2 files changed, 477 insertions(+) create mode 100644 .claude/commands/analyze-crash.md create mode 100644 .claude/commands/analyze-error.md diff --git a/.claude/commands/analyze-crash.md b/.claude/commands/analyze-crash.md new file mode 100644 index 000000000000..3a761416bdb4 --- /dev/null +++ b/.claude/commands/analyze-crash.md @@ -0,0 +1,201 @@ +# Stack Trace Crash Analysis for dd-trace-dotnet + +You are analyzing a crash stack trace for the dd-trace-dotnet repository. Perform a comprehensive investigation to help engineers understand and triage the crash. Focus on de-mystifying the crashing thread and explaining how the crash occurred. + +## Input Processing +The user has provided a crash stack trace. Parse and analyze it systematically. + +## Analysis Workflow + +## GitHub Link Generation + +When referencing files in the dd-trace-dotnet repository, always provide clickable GitHub links in addition to local paths: + +**Format**: +``` +[filename:line](https://github.com/DataDog/dd-trace-dotnet/blob/master/path/to/file#Lline) +``` + +**Examples**: +- Single line: `[cor_profiler.cpp:1430](https://github.com/DataDog/dd-trace-dotnet/blob/master/tracer/src/Datadog.Tracer.Native/cor_profiler.cpp#L1430)` +- Line range: `[rejit_handler.cpp:263-296](https://github.com/DataDog/dd-trace-dotnet/blob/master/tracer/src/Datadog.Tracer.Native/rejit_handler.cpp#L263-L296)` + +**When to use**: +- All file:line references in Executive Summary +- Stack Trace Classification table "Location" column (when file paths are available) +- All code context section headings +- Related Code section + +**Path construction**: +- Base URL: `https://github.com/DataDog/dd-trace-dotnet/blob/master/` +- Append the repository-relative path (strip `C:\Users\...\dd-trace-dotnet\` or similar prefixes) +- Add `#L{lineNumber}` for single line or `#L{start}-L{end}` for ranges +- Example: Local path `C:\Users\...\dd-trace-dotnet\tracer\src\Datadog.Tracer.Native\cor_profiler.cpp:1430` becomes `[cor_profiler.cpp:1430](https://github.com/DataDog/dd-trace-dotnet/blob/master/tracer/src/Datadog.Tracer.Native/cor_profiler.cpp#L1430)` + +### Phase 1: Parse & Classify Stack Frames + +Extract all stack frames and classify each one: + +**Classification Categories:** +- **CLR Runtime**: Functions like `ReJitManager::`, `ProfToEEInterfaceImpl::`, `ICorProfiler*`, CLR DLL references (clr.dll, coreclr.dll, mscorwks.dll) +- **dd-trace-dotnet Native**: Namespace patterns (`trace::`, `debugger::`, `fault_tolerant::`, `iast::`), or paths containing `Datadog.Tracer.Native` +- **dd-trace-dotnet Managed**: References to `Datadog.Trace.dll!` +- **External/Application**: Everything else (customer code, third-party libraries, framework code) + +Create a classification table showing frame number, type, location, and brief description. + +### Phase 2: Locate dd-trace-dotnet Code + +For each dd-trace-dotnet frame that includes file path and line number: + +1. **Extract and normalize path**: Remove build-specific prefixes + - Strip: `c:\mnt\`, `D:\a\_work\1\s\`, `/home/runner/work/dd-trace-dotnet/`, etc. + - Result should be relative to repo root: `tracer/src/Datadog.Tracer.Native/{filename}` + +2. **Find file in repository**: + - First try direct path match + - If not found, use Glob tool with pattern: `**/Datadog.Tracer.Native/**/{filename}` + - If still not found, try just the filename: `**/{filename}` + +3. **Read code with context**: + - Find the function containing the crash line + - Include 10-15 lines before the crash line + - Mark or highlight the actual crash line + - Include 5-10 lines after + - Show enough context to understand what the code is doing + +### Phase 3: Code Context Extraction + +For each critical dd-trace-dotnet frame: +1. Show the function signature +2. Include surrounding code (described in Phase 2) +3. **Clearly mark the crash line** with a comment like `// >>> CRASH POINT <<<` +4. Explain what this code does +5. Explain why it crashed based on the evidence + +Format each code section as: +``` +### Frame X: {function_name} ([{file}:{line}](GitHub link)) + +​```cpp +// {file}:{start_line}-{end_line} +{code with crash line marked} +​``` + +**Analysis**: {Explanation of what this code does and why it failed} +``` + +### Phase 4: Reconstruct Crash Flow + +Build a narrative explaining the execution flow leading to the crash. This is the primary goal of the analysis - to help engineers understand what happened: + +1. **Entry point**: Where did execution start? (e.g., profiler callback, background thread loop) +2. **Key operations**: What was the code trying to do? +3. **Critical transitions**: Where did control flow between components? +4. **Failure point**: Where and why did it crash? +5. **Crash type**: Describe what type of crash this is (e.g., null pointer dereference, access violation, invalid module reference, race condition, etc.) + +Write this as a clear, step-by-step narrative that someone unfamiliar with the code can follow. Focus on explaining HOW the crash happened based on the evidence in the stack trace and code, without prescribing a specific fix. + +### Phase 5: Identify Related Code + +Use Bash tool with git commands to find relevant context, focusing on commits associated with PRs: + +1. Check recent commits to the affected files: `git log --oneline -10 {file}` +2. Search for related changes: `git log --grep="crash" --grep="fix" --oneline -20` (use keywords relevant to the crash area) +3. For each relevant commit, check if it's associated with a PR: + - Look for PR numbers in commit messages (e.g., "(#1234)" or "PR #1234") + - If found, construct PR link: `https://github.com/DataDog/dd-trace-dotnet/pull/{number}` +4. Prioritize commits with PR associations - these have more context +5. Look for similar code patterns in other files that might provide context + +**Focus on commits with PR links** - PRs provide valuable context including descriptions, discussions, and rationale that individual commits lack. + +## Output Format + +Generate a well-formatted markdown document with these sections: + +```markdown +# Crash Analysis Report +**Generated**: {ISO 8601 timestamp} + +## Executive Summary +{2-3 sentence summary of what crashed and where in the code. Focus on demystifying the crash location and describing what the crashing thread was doing.} + +## Stack Trace Classification + +### Crashed Thread: #{thread_number} + +| # | Type | Location | Description | +|---|------|----------|-------------| +| 0 | {type} | {function/location} | {brief description} | +| 1 | {type} | {function/location} | {brief description} | +| ... | ... | ... | ... | + +{If multiple threads provided, note other interesting threads but focus on crashed thread} + +## Code Context + +{For each critical dd-trace-dotnet frame, show code with analysis} + +### Frame X: {function} ([{file}:{line}](GitHub link)) + +​```cpp +{code snippet with crash line marked} +​``` + +**Analysis**: {Explanation of what this code does} + +## Crash Flow Reconstruction + +{Step-by-step narrative explaining the execution flow from start to crash point} + +**Crash Type**: {Description of what type of crash this is - e.g., null pointer dereference, access violation, invalid module reference, race condition} + +**How it happened**: {Clear explanation of the sequence of events that led to the crash based on the stack trace and code analysis} + +## Related Code + +**Relevant PRs and commits**: +- [#{PR number}](https://github.com/DataDog/dd-trace-dotnet/pull/{PR number}): {PR title/description} - {why relevant} +- [#{PR number}](https://github.com/DataDog/dd-trace-dotnet/pull/{PR number}): {PR title/description} - {why relevant} + +{Only include commits without PR associations if they are particularly relevant} + +**Related code locations**: +- [{file}:{line}](GitHub link) - {description} +- [{file}:{line}](GitHub link) - {description} + +## Additional Context + +{Any additional useful context about the application environment, runtime, features in use, or relevant background} + +--- +*Analysis generated by Claude Code /analyze-crash command* +*This analysis is intended to help understand and triage the crash. Engineers should review this analysis to determine if a code fix is needed.* +``` + +## Output File Management + +1. **Create output directory**: Use Bash to create `~/.claude/analysis/` if it doesn't exist +2. **Generate filename**: Use format `crash-analysis-{YYYYMMDD-HHMMSS}.md` (e.g., `crash-analysis-20250316-143022.md`) +3. **Save file**: Write the markdown analysis to the file +4. **Return path**: Tell the user the full path where the analysis was saved + +## Important Guidelines + +- **Focus on triage and understanding**: The goal is to help engineers understand HOW the crash happened, not to prescribe specific fixes +- **Describe crash types**: It's okay to identify what type of crash this is (e.g., null pointer, race condition, invalid reference), but don't match against fixed "patterns" +- **End at explanation**: Phase 4 (Crash Flow Reconstruction) should provide a clear explanation of how the crash occurred. Engineers will then decide on fixes +- **No fix suggestions**: Do not suggest code changes, patches, or specific implementation fixes. Focus on analysis only +- **Handle path variations gracefully**: Stack traces from different build environments will have different path prefixes +- **Continue with missing information**: If a file can't be located, note this but continue the analysis with available information +- **Focus on the crashed thread**: If multiple threads are provided, focus primarily on the crashed thread but mention other relevant threads +- **Be concise but thorough**: Provide enough detail to understand the issue without unnecessary verbosity +- **Always include GitHub links**: Every file:line reference should have a clickable GitHub link to master branch +- **Prefer PR links over commits**: When git log finds relevant commits, prioritize those associated with PRs. Extract PR numbers from commit messages (e.g., "(#1234)") and link to the PR: `https://github.com/DataDog/dd-trace-dotnet/pull/{number}`. Only include standalone commit links if particularly relevant and not part of a PR +- **Mark uncertainties**: If something is unclear or speculative, explicitly state this + +## Now Analyze + +Parse the stack trace provided by the user and follow the workflow above to generate a comprehensive crash analysis. diff --git a/.claude/commands/analyze-error.md b/.claude/commands/analyze-error.md new file mode 100644 index 000000000000..03f2d1818ec1 --- /dev/null +++ b/.claude/commands/analyze-error.md @@ -0,0 +1,276 @@ +# Error Stack Trace Analysis for dd-trace-dotnet + +You are analyzing an error stack trace from the dd-trace-dotnet library. These errors originated from customer applications but are caused by dd-trace-dotnet. Your goal is to understand the error, determine if it provides enough information to identify the root cause, and recommend a fix ONLY if the error is actionable within dd-trace-dotnet. + +## Input Processing +The user has provided an error stack trace. Parse and analyze it systematically. + +## Analysis Workflow + +## GitHub Link Generation + +When referencing files in the dd-trace-dotnet repository, always provide clickable GitHub links to the master branch: + +**Format**: +``` +[filename:line](https://github.com/DataDog/dd-trace-dotnet/blob/master/path/to/file#Lline) +``` + +**Examples**: +- Single line: `[PerformanceCountersListener.cs:123](https://github.com/DataDog/dd-trace-dotnet/blob/master/tracer/src/Datadog.Trace/RuntimeMetrics/PerformanceCountersListener.cs#L123)` +- Line range: `[DataStreamsWriter.cs:45-60](https://github.com/DataDog/dd-trace-dotnet/blob/master/tracer/src/Datadog.Trace/DataStreamsMonitoring/DataStreamsWriter.cs#L45-L60)` + +**Path construction**: +- Base URL: `https://github.com/DataDog/dd-trace-dotnet/blob/master/` +- Append the repository-relative path (strip workspace prefixes) +- Add `#L{lineNumber}` for single line or `#L{start}-L{end}` for ranges + +### Phase 1: Parse & Classify Stack Frames + +Extract all stack frames and classify each one: + +**Classification Categories:** +- **dd-trace-dotnet**: Methods in `Datadog.Trace.*` namespaces +- **CLR Runtime**: Framework methods (System.*, Microsoft.*, etc.) +- **REDACTED**: Frames marked as REDACTED in the stack trace +- **External/Application**: Other identifiable frames + +Create a classification table showing frame number, type, location, and brief description. + +**Important**: +- REDACTED frames indicate customer/application code that we cannot see +- We have NO information about what happens in REDACTED frames +- Do NOT speculate about REDACTED frame behavior + +### Phase 2: Locate dd-trace-dotnet Code + +For each dd-trace-dotnet frame that includes file path, method name, or line number: + +1. **Search for the method/class**: + - Use Glob to find files matching the class name: `**/{ClassName}.cs` + - If the namespace is known, search within the appropriate directory structure + - For example, `Datadog.Trace.RuntimeMetrics.PerformanceCountersListener` → `tracer/src/Datadog.Trace/RuntimeMetrics/PerformanceCountersListener.cs` + +2. **Read code with context**: + - Find the method mentioned in the stack trace + - Include enough context to understand what the code is doing + - Show the relevant code path that leads to the error + - If a line number is available, focus on that specific line + +### Phase 3: Code Context Extraction + +For each critical dd-trace-dotnet frame: +1. Show the function/method signature +2. Include surrounding code +3. **Highlight the error point** (if line number available) +4. Explain what this code does +5. Explain what likely went wrong based on the exception type and message + +Format each code section as: +``` +### Frame X: {method_name} ([{file}:{line}](GitHub link)) + +​```csharp +// {file}:{start_line}-{end_line} +{code with error point marked if available} +​``` + +**Analysis**: {Explanation of what this code does and what went wrong} +``` + +### Phase 4: Error Flow Reconstruction + +Build a narrative explaining the execution flow leading to the error: + +1. **Entry point**: Where did execution likely start? (e.g., background task, instrumentation callback) +2. **Key operations**: What was the code trying to do? +3. **Error point**: Where did the exception occur and why? +4. **Exception type**: What does this exception typically indicate? +5. **Context**: Are there REDACTED frames that might be relevant but unknowable? + +Write this as a clear, step-by-step narrative focused on HOW the error occurred. + +**Important considerations**: +- Log messages are constant templates - we don't have the actual runtime values +- REDACTED frames are unknown - acknowledge their presence but don't speculate +- Stack trace may be from an older version of the tracer + +### Phase 5: Actionability Assessment + +Determine if this error is actionable within dd-trace-dotnet. Consider: + +**Actionable IF**: +- The error occurs entirely within dd-trace-dotnet code +- The root cause can be identified from the stack trace +- There's a code path in dd-trace-dotnet that can be fixed to prevent the error +- The error indicates a bug, race condition, or incorrect assumption in dd-trace-dotnet + +**NOT Actionable IF**: +- The error originates from framework/CLR code that dd-trace-dotnet calls +- The error is a consequence of invalid application state (unknown to us) +- Critical frames are REDACTED and we cannot determine the actual cause +- The error is expected behavior under certain conditions +- The error is environmental (missing dependencies, permissions, etc.) + +### Phase 6: Version Analysis + +Use Bash tool with git commands to check if this might be a known or fixed issue: + +1. Search for related fixes: `git log --grep="keyword" --oneline -20` (use keywords from the error message or affected area) +2. Check recent commits to affected files: `git log --oneline -10 {file}` +3. Look for related PRs in commit messages (e.g., "(#1234)") +4. If found, construct PR links: `https://github.com/DataDog/dd-trace-dotnet/pull/{number}` + +Note: The stack trace may be from an older version, so a fix may already exist in master. + +## Output Format + +Generate a well-formatted markdown document with these sections: + +```markdown +# Error Analysis Report +**Generated**: {ISO 8601 timestamp} + +## Executive Summary +{2-3 sentence summary of what error occurred, where in the code, and whether it's actionable} + +## Error Details + +**Error Message**: `{error message template}` +**Exception Type**: `{exception type}` +**Source**: Customer application instrumented with dd-trace-dotnet + +## Stack Trace Classification + +| # | Type | Location | Description | +|---|------|----------|-------------| +| 0 | {type} | {method/location} | {brief description} | +| 1 | {type} | {method/location} | {brief description} | +| ... | ... | ... | ... | + +**Note**: REDACTED frames indicate customer/application code. We have no visibility into these frames. + +## Code Context + +{For each critical dd-trace-dotnet frame, show code with analysis} + +### Frame X: {method} ([{file}:{line}](GitHub link)) + +​```csharp +{code snippet} +​``` + +**Analysis**: {Explanation of what this code does} + +## Error Flow Reconstruction + +{Step-by-step narrative explaining how the error occurred} + +**Exception Type**: {What this exception typically indicates} + +**How it happened**: {Clear explanation of the sequence of events based on the stack trace and code analysis} + +**Unknown Factors**: {Note any REDACTED frames or missing information that limits our understanding} + +## Actionability Assessment + +### Is This Error Actionable? +{YES or NO with clear justification} + +{If NO, explain why:} +- {Reason 1} +- {Reason 2} + +{If YES, explain what can be fixed in dd-trace-dotnet} + +## Version Analysis + +**Potentially Related Changes**: +{If found, list related PRs and commits} +- [#{PR number}](https://github.com/DataDog/dd-trace-dotnet/pull/{PR number}): {PR title} - {why relevant} + +{If no related changes found} +- No recent changes found related to this error area + +**Note**: The stack trace may be from an older version. Check if the issue persists in the latest version. + +## Recommended Action + +### {If Actionable} + +**Recommended Fix**: +{Describe the code change needed in dd-trace-dotnet to prevent this error} + +**Implementation Details**: +- {File to modify}: [{file}](GitHub link) +- {What to change}: {specific change description} +- {Why this fixes it}: {explanation} + +**Testing**: +- {How to test the fix} +- {What scenarios to cover} + +### {If NOT Actionable} + +**Recommended Action**: Mark this error as **Ignored** in Error Tracking + +**Code Change**: Update the log statement to use `Log.ErrorSkipTelemetry` instead of `Log.Error` + +**Reason**: {Explain why this error is not actionable and should not be tracked} + +**File to Update**: [{file}](GitHub link to the file containing the Log.Error call) + +## Additional Context + +{Any additional useful context about the error, affected features, or environmental factors} + +--- +*Analysis generated by Claude Code /analyze-error command* +*This analysis determines if the error is actionable within dd-trace-dotnet and provides recommendations accordingly.* +``` + +## Output File Management + +1. **Create output directory**: Use Bash to create `~/.claude/analysis/` if it doesn't exist +2. **Generate filename**: Use format `error-analysis-{YYYYMMDD-HHMMSS}.md` (e.g., `error-analysis-20250316-143022.md`) +3. **Save file**: Write the markdown analysis to the file +4. **Return path**: Tell the user the full path where the analysis was saved + +## Important Guidelines + +### DO NOT Recommend +- **Try/Catch blocks**: Catching exceptions is virtually NEVER the correct solution +- **Application code changes**: We don't control customer applications +- **Application environment variable changes**: We can't modify customer environments +- **Suppressing errors indiscriminately**: Only use ErrorSkipTelemetry when genuinely not actionable + +### DO Recommend (When Actionable) +- **Null checks**: If dereferencing could fail +- **Validation**: If invalid state leads to errors +- **Synchronization**: If race conditions are evident +- **Defensive coding**: If assumptions might be violated +- **Better error handling**: If we can gracefully handle edge cases +- **Bug fixes**: If there's a clear logic error + +### DO Recommend (When NOT Actionable) +- **Mark as Ignored** in Error Tracking +- **Change Log.Error to Log.ErrorSkipTelemetry** in the specific file +- Clear explanation of why it's not actionable + +### Analysis Constraints +- **REDACTED frames are black boxes**: Don't speculate about their behavior +- **Log messages are templates**: Don't assume specific runtime values +- **Stack traces may be old**: Note if the code has changed since +- **Link to master branch**: All GitHub links should point to current code +- **Focus on dd-trace-dotnet**: Only recommend changes within our codebase + +### Quality Standards +- **Be concise but thorough**: Provide enough detail without unnecessary verbosity +- **Be definitive on actionability**: Clearly state YES or NO with justification +- **Provide specific fixes**: If actionable, describe exactly what to change +- **Acknowledge limitations**: Explicitly state when information is missing or uncertain +- **Link everything**: Every file reference should have a GitHub link + +## Now Analyze + +Parse the error stack trace provided by the user and follow the workflow above to generate a comprehensive error analysis with actionability assessment and recommendations. From 752df5416c5c68ec83b420f7b7ed92a378ac3d57 Mon Sep 17 00:00:00 2001 From: Steven Bouwkamp Date: Wed, 17 Dec 2025 10:59:23 -0500 Subject: [PATCH 2/2] Attempt to fix file creation issues and provide better analysis --- .claude/commands/analyze-crash.md | 5 ++++- .claude/commands/analyze-error.md | 30 +++++++++++++++++++++++------- 2 files changed, 27 insertions(+), 8 deletions(-) diff --git a/.claude/commands/analyze-crash.md b/.claude/commands/analyze-crash.md index 3a761416bdb4..523ce216a2c3 100644 --- a/.claude/commands/analyze-crash.md +++ b/.claude/commands/analyze-crash.md @@ -177,7 +177,10 @@ Generate a well-formatted markdown document with these sections: ## Output File Management -1. **Create output directory**: Use Bash to create `~/.claude/analysis/` if it doesn't exist +1. **Create output directory**: + - On Windows: Use `powershell.exe -NoProfile -Command 'New-Item -ItemType Directory -Force -Path (Join-Path $env:USERPROFILE ".claude\analysis") | Select-Object -ExpandProperty FullName'` + - On Linux/Mac: Use `mkdir -p ~/.claude/analysis && echo ~/.claude/analysis` + - **IMPORTANT**: On Windows, you MUST use single quotes around the PowerShell command to prevent bash from interpreting `$env:USERPROFILE` 2. **Generate filename**: Use format `crash-analysis-{YYYYMMDD-HHMMSS}.md` (e.g., `crash-analysis-20250316-143022.md`) 3. **Save file**: Write the markdown analysis to the file 4. **Return path**: Tell the user the full path where the analysis was saved diff --git a/.claude/commands/analyze-error.md b/.claude/commands/analyze-error.md index 03f2d1818ec1..49d6e709440e 100644 --- a/.claude/commands/analyze-error.md +++ b/.claude/commands/analyze-error.md @@ -97,20 +97,23 @@ Write this as a clear, step-by-step narrative focused on HOW the error occurred. ### Phase 5: Actionability Assessment -Determine if this error is actionable within dd-trace-dotnet. Consider: +Determine if this error is actionable within dd-trace-dotnet. **Default to YES (actionable) unless there's clear evidence otherwise.** -**Actionable IF**: +**Actionable (YES) IF**: - The error occurs entirely within dd-trace-dotnet code - The root cause can be identified from the stack trace - There's a code path in dd-trace-dotnet that can be fixed to prevent the error - The error indicates a bug, race condition, or incorrect assumption in dd-trace-dotnet -**NOT Actionable IF**: +**NOT Actionable (NO) IF**: - The error originates from framework/CLR code that dd-trace-dotnet calls - The error is a consequence of invalid application state (unknown to us) - Critical frames are REDACTED and we cannot determine the actual cause - The error is expected behavior under certain conditions - The error is environmental (missing dependencies, permissions, etc.) +- **AND** you have explicit proof from PR descriptions/commits that this exact error was already fixed + +**IMPORTANT**: Do NOT mark as "not actionable" just because you found a PR that touched the same area. You need explicit evidence that this specific error scenario was fixed. ### Phase 6: Version Analysis @@ -121,7 +124,12 @@ Use Bash tool with git commands to check if this might be a known or fixed issue 3. Look for related PRs in commit messages (e.g., "(#1234)") 4. If found, construct PR links: `https://github.com/DataDog/dd-trace-dotnet/pull/{number}` -Note: The stack trace may be from an older version, so a fix may already exist in master. +**CRITICAL - Do NOT assume a PR fixed this error unless**: +- The PR explicitly mentions fixing this EXACT exception type and error message +- The PR description or commit messages reference the specific bug being reported +- You can verify that the code changes would prevent this exact error scenario + +**A PR that touches the same file or area is NOT sufficient evidence** - it might have fixed a different issue or even introduced this one. Default to treating the error as actionable unless you have clear proof it's fixed. ## Output Format @@ -187,12 +195,17 @@ Generate a well-formatted markdown document with these sections: **Potentially Related Changes**: {If found, list related PRs and commits} -- [#{PR number}](https://github.com/DataDog/dd-trace-dotnet/pull/{PR number}): {PR title} - {why relevant} +- [#{PR number}](https://github.com/DataDog/dd-trace-dotnet/pull/{PR number}): {PR title} - {why relevant and whether it definitively fixes THIS error} {If no related changes found} - No recent changes found related to this error area -**Note**: The stack trace may be from an older version. Check if the issue persists in the latest version. +**IMPORTANT**: Just because a PR touched this code area does NOT mean it fixed this error. Only conclude an error is fixed if: +1. The PR explicitly mentions this exception type and scenario +2. The code changes clearly prevent this exact error +3. The PR description or commits reference this specific bug + +Otherwise, treat the error as NEW and actionable. ## Recommended Action @@ -231,7 +244,10 @@ Generate a well-formatted markdown document with these sections: ## Output File Management -1. **Create output directory**: Use Bash to create `~/.claude/analysis/` if it doesn't exist +1. **Create output directory**: + - On Windows: Use `powershell.exe -NoProfile -Command 'New-Item -ItemType Directory -Force -Path (Join-Path $env:USERPROFILE ".claude\analysis") | Select-Object -ExpandProperty FullName'` + - On Linux/Mac: Use `mkdir -p ~/.claude/analysis && echo ~/.claude/analysis` + - **IMPORTANT**: On Windows, you MUST use single quotes around the PowerShell command to prevent bash from interpreting `$env:USERPROFILE` 2. **Generate filename**: Use format `error-analysis-{YYYYMMDD-HHMMSS}.md` (e.g., `error-analysis-20250316-143022.md`) 3. **Save file**: Write the markdown analysis to the file 4. **Return path**: Tell the user the full path where the analysis was saved