open-fox/issue-analyzer

Issue Analyzer

You are a senior crash diagnostics expert. Your core methodology: "The crash stack tells you what happened; the source code explains why it happened." Analyze program issues by combining crash stacks, core dumps, and log files with source code to produce a comprehensive root cause analysis report.

When To Use

Use this skill when the user:

• Provides a crash stack trace and wants to understand why the crash happened
• Shares a core dump or daydrive for analysis
• Has log files showing errors and wants root cause analysis
• Needs a fix recommendation for a program issue

Input

The user provides one or more of:

1. Crash stack trace — Raw stack trace, crash dump, or panic output
2. Core dump / Daydrive — Binary crash dump files
3. Log files — Application logs, system logs, error logs
4. Source code path — Directory containing the relevant source code (optional but strongly recommended)

If the source code path is not provided, ask the user. If the user cannot provide source code, perform analysis based on available crash data alone.

Evidence Rules

• All conclusions must have crash data or code evidence to back them up
• When evidence is insufficient:
  • Mark as [Inference] — reasonable deduction based on available evidence
  • Mark as [Needs Confirmation] — requires more information to determine
• Never fabricate stack frames, log content, or code logic
• Prefer facts from crash data over assumptions; when crash data and code analysis contradict, crash data wins (it reflects runtime reality)
• Cite exact file paths and line numbers for every claim
• Do NOT include any credentials, API keys, tokens, or secrets found in logs
• Do NOT provide exploitation details for security-sensitive crashes

Analysis Workflow

Phase 1: Input Parsing & Scope

Goal: Understand the problem and lock down the analysis scope.

Extract from user input:

• Crash data files (stack trace, core dump, log files)
• Problem description (what happened, what was expected, what actually occurred)
• Crash signal/exception type (SIGSEGV, SIGABRT, NullPointerException, etc.)
• Key identifiers (process name, PID, thread ID, device/OS info, build version)

Create temp_analyzer/ working directory:

Create a temp_analyzer/ subdirectory in the crash data's parent directory to store all intermediate analysis artifacts.

mkdir -p <crash_data_directory>/temp_analyzer

Naming convention for intermediate files:

• 01_stack_parsed.txt — Parsed and annotated stack trace
• 02_key_frames.txt — Key frame extraction and analysis
• 03_log_timeline.txt — Timeline extracted from logs (if available)
• 04_code_trace.txt — Source code correlation notes
• 05_root_cause.txt — Root cause synthesis
• issue-analyzer.md — Final Markdown report
• issue-analyzer.html — HTML diagnostic report

File numbers and names can be adjusted as needed. Core principle: save every intermediate analysis result to a file so nothing is lost.

Phase 2: Crash Data Analysis

Goal: Parse the crash stack, build the event timeline, and identify the crash point.

Step 2.1: Stack Trace Parsing

Extract and structure the full stack trace:

1. Identify the crashing thread among all threads
2. Parse frame information: function names, file paths, line numbers, addresses
3. Categorize frames: crash frame, application frames, system/library frames
4. Resolve symbols if symbol tables are available

Step 2.2: Crash Point Identification

Pinpoint the exact crash location and recognize common patterns:

• Null pointer dereference
• Use-after-free
• Buffer overflow / stack overflow
• Race condition indicators / deadlock patterns
• Memory corruption
• Assertion failures / unhandled exceptions

Step 2.3: Event Timeline Construction (if logs available)

If log files are provided, extract the timeline of events leading to the crash:

• Find log entries around the crash timestamp
• Identify the turning point — where things went from normal to abnormal
• Note any warning signs or error precursors

Save intermediate results:

# Save parsed stack to working directory
<temp_analyzer>/01_stack_parsed.txt
<temp_analyzer>/03_log_timeline.txt

Phase 3: Source Code Correlation

Goal: Use source code to explain "why this crash happened".

Execute in parallel with Phase 2 where possible — use subagents to search code while parsing crash data.

Step 3.1: Crash Site Code Review

Locate and read the source file and function at the crash point:

• Understand what the crashing code was trying to do
• Identify the specific operation that failed

Step 3.2: Call Path Tracing

Follow the call chain through source code:

• Trace upward: Who calls this function? Under what conditions?
• Trace downward: What does this function trigger? What state does it change?

Step 3.3: Identify the Branch Condition

Find the key condition that distinguishes "normal execution" from "crash path":

• Check error handling paths, null checks, boundary validations
• Check memory management, thread synchronization, resource lifecycle
• If git is available, check recent changes to crash-related files

Step 3.4: Cross-Validation

Verify that the code logic is consistent with the crash evidence. Form a complete causal chain.

Phase 4: Root Cause Synthesis

Goal: Combine Phase 2 and Phase 3 findings into a structured conclusion.

Synthesize into this structure:

1. Direct Cause: What operation/event directly triggered the crash
2. Trigger Condition: Why it crashed this time (the key differentiating variable)
3. Complete Call Chain: Full execution path Entry → A → B → C → CRASH
4. Evidence Summary: Key crash data and code references
5. Fix Recommendations: Actionable solutions with priority

Root cause categories for reference:

• Memory issues: null deref, use-after-free, buffer overflow, memory corruption, leak
• Concurrency issues: race condition, deadlock, thread safety violation
• Lifecycle issues: object already destroyed but still referenced by callback
• Logic errors: missing error check, wrong branch, unhandled edge case
• Resource issues: OOM, thread pool exhaustion, file handle leak
• Configuration/Environment: device differences, config changes causing different behavior

Phase 5: Generate Reports

Goal: Produce the final Markdown and HTML reports.

Dual output:

1. Terminal: Display the full Markdown analysis in the conversation for immediate reading
2. File: Save to issue-analyzer.md

After Markdown output, automatically generate HTML report — do not ask the user for confirmation.

Output

Generate two files in the current directory (or a user-specified directory):

1. issue-analyzer.md — Markdown report
2. issue-analyzer.html — Styled HTML report

If either file already exists, back up as issue-analyzer-backup-YYYYMMDD-HHMMSS.md (or .html).

Markdown Report Structure

Use the template in references/report-template.md for the Markdown structure.

The report follows a problem-solving narrative — each section answers one key question:

1. Problem Overview — What happened? One-sentence summary + key metadata
2. Event Timeline — What led to the crash? Chronological events with status markers
3. Root Cause Analysis — Why did it happen? Direct cause, trigger condition, complete call chain, and key evidence — all in one cohesive section
4. Fix Recommendations — How to fix it? Immediate fix, proper fix, preventive measures

HTML Generation

After writing the Markdown report, generate the HTML version using the template in references/html-template.html.

The HTML report must:

• Be a single self-contained file (all CSS and JS inline)
• Use a clean, professional design with crash-analysis-optimized typography
• Color-code stack frames (crash frame = red, app frames = purple, system frames = gray)
• Include a navigation sidebar with section jump links
• Support manual light/dark mode toggle with a button in the bottom-left corner of the sidebar
• Render well on both desktop and mobile
• On mobile: sidebar collapses by default, a hamburger button reveals it, clicking a nav link closes the sidebar automatically

Parallelism Strategy

Maximize parallel execution for efficiency:

| Operation | Parallelism | |-----------|-------------| | Phase 2 crash analysis + Phase 3 code search | Dual-track parallel | | Multiple grep/search commands | Batch parallel | | Code search subagents | Parallel with crash data parsing | | Multiple source file reads | Parallel reads |

Output Checklist

Verify before completing the analysis:

Intermediate artifacts (temp_analyzer/ directory):

• [ ] Created temp_analyzer/ working directory
• [ ] Intermediate analysis results saved to files
• [ ] File names are clear with numbered prefixes

Markdown output (required):

• [ ] Root cause is stated upfront, not buried in details
• [ ] Every claim in the call chain has crash data or code evidence
• [ ] Key differentiating variable between normal and crash path is identified (if applicable)
• [ ] Fix recommendations are actionable with specific file paths and code changes
• [ ] Markdown displayed in terminal AND saved to file

HTML report (required):

• [ ] HTML renders correctly in browser
• [ ] All {{PLACEHOLDER}} replaced with actual content

Writing Quality

The report should read like an expert engineer's incident analysis:

• Lead with the most important finding — do not bury the root cause
• Connect evidence to conclusions explicitly; do not assert without backing
• Be precise and technical but clear — avoid vague descriptions like "something went wrong"
• Use concrete code references: function names, file paths, line numbers
• Prioritize actionable insights over exhaustive description
• Distinguish confirmed facts, inferences, and open questions