investigation

name	investigation
description	Bug investigation workflow using GitHub MCP. Use when users report bugs, errors, or unexpected behavior that need investigation. Handles duplicate checking, incremental issue updates, root cause analysis, and adding diagnostic logging/tests. In this skill's workflow: investigate and document findings, but do NOT fix the bug itself. Other workflows/agents may fix bugs separately.

Bug Investigation

Investigate bugs systematically: check for duplicates, create/update GitHub issues incrementally, add diagnostic logging and tests, and document root cause analysis.

Critical Rules

1. NO bug fixes in this workflow - Only investigate and document findings. Do not modify code to fix the bug (separate workflows/agents may handle fixes).
2. Tests are mandatory - Add reproduction test case marked with @pytest.mark.xfail (test must FAIL with current code).
3. Diagnostic code allowed - Add logging statements to aid investigation (follows format/level requirements).
4. Detailed GitHub documentation - Root cause analysis with affected code paths MUST go in the GitHub issue.
5. Incremental updates - Update GitHub issue as findings emerge. Do not wait until investigation is complete.
6. Logging stays - Diagnostic logs should have appropriate log levels and remain after investigation.
7. GitHub is the deliverable - All findings MUST be documented in GitHub issues. Do NOT create local markdown files.

Deliverable Requirements

Primary deliverables: Bug discovery, detailed analysis, and reproduction test.

Investigation is NOT complete until:

• GitHub issue created with initial bug report and detailed findings
• Issue includes complete root cause analysis with code paths
• Reproduction test case added (can be marked as @pytest.mark.xfail)
• Diagnostic logging added with proper format and levels
• Issue status updated to "Investigation complete"

Required artifacts:

1. GitHub Issue - Detailed bug analysis documenting:
   • Exact reproduction steps
   • Root cause with affected code locations
   • Expected vs actual behavior
   • Related commits/dependencies
2. Reproduction Test - Unit test that demonstrates the bug exists (test should FAIL with current code)
   • Mark with @pytest.mark.xfail(reason="Bug #123: ...") if it needs to stay in test suite
   • Test verifies bug exists without fixing it
3. Diagnostic Logging - Traces added to aid understanding (follows log format/level requirements)

Do NOT create local markdown files. All findings go directly to GitHub issues. No investigation/findings-*.md or similar files.

Investigation Workflow

Step 1: Check for Duplicates

Before investigating, search for existing bug reports:

Use GitHub MCP search_issues with query containing:
- Error message keywords
- Affected component/file names
- Symptom description

If duplicate found: Link to existing issue, add any new information as a comment, and stop.

If no duplicate: Proceed to Step 2.

Step 2: Create Initial Issue

Create a GitHub issue immediately with available information:

## Bug Report

### Summary
[Brief description of the bug]

### Status
🔍 Investigation in progress

### Observed Behavior
[What actually happens]

### Expected Behavior
[What should happen]

### Reproduction Steps
[Known steps so far - will be refined]

### Environment
- [Version, OS, dependencies if known]

### Investigation Log
- [Timestamp]: Started investigation

Use mcp__github__issue_write with method: "create".

Step 3: Gather Context

Collect information about the bug:

1. Error traces - Stack traces, error messages, logs
2. Affected code paths - Use Grep/Glob to find relevant code
3. Recent changes - Check git history for related modifications
4. Dependencies - Version mismatches, breaking changes

Update the issue incrementally as findings emerge.

Step 4: Add Diagnostic Logging

Add logging statements to trace execution flow. See references/logging-guidelines.md for log level guidance.

IMPORTANT: Log Format Requirements (from CLAUDE.md):

1. Use %(funcName)s in log format to automatically include function names - do NOT manually prefix messages
2. Use named placeholders instead of positional arguments for readability
3. Never use redundant manual prefixes like [function_name]

IMPORTANT: Log Level Selection:

• DEBUG (default for diagnostic logging): Detailed execution traces, variable values, control flow
  • Use this for most diagnostic logging during investigation
  • Can be disabled in production by setting log level to INFO
  • Examples: entering/exiting functions, intermediate values, decision points
• INFO: Significant state changes or milestones (e.g., "processing completed")
  • Use sparingly for important business events
  • Visible in production logs by default
• WARNING: Suspicious but non-fatal conditions that warrant attention
  • Use for unexpected values, recoverable errors, edge cases
  • Always visible unless explicitly suppressed

# Example: Adding investigation logging
import logging
logger = logging.getLogger(__name__)

# ✓ GOOD - DEBUG for detailed execution tracing (most diagnostic logs)
logger.debug("input_size=%(size)d preview=%(preview)r", {"size": len(input_data), "preview": input_data[:100]})

# ✓ GOOD - DEBUG for intermediate values during processing
logger.debug("iteration=%(i)d current_value=%(val)r", {"i": i, "val": current_value})

# ✓ GOOD - INFO for significant milestones (less frequent)
logger.info("result_count=%(count)d elapsed=%(time).2fs", {"count": len(results), "time": elapsed})

# ✓ GOOD - WARNING for suspicious but non-fatal conditions
logger.warning("unexpected_null_field=%(field)s record_id=%(id)s", {"field": field_name, "id": record_id})

# ✗ BAD - using INFO/WARNING for routine diagnostic data
# logger.info("entering process_data function")  # Should be DEBUG
# logger.warning("processing item %(id)d", {"id": item_id})  # Should be DEBUG

# ✗ BAD - positional arguments (hard to read)
# logger.debug("Entering process_data with input: %s", input_data)

# ✗ BAD - manual function name prefix (redundant, log format should include %(funcName)s)
# logger.debug("[process_data] input_size=%d", len(input_data))

Log format example (configure in logging.local.ini):

[formatter_standard]
format=%(asctime)s - %(name)s - %(funcName)s - %(levelname)s - %(message)s

Commit diagnostic logging with message: chore: add diagnostic logging for [issue-number] investigation

Step 5: Add Reproduction Tests

CRITICAL: Reproduction tests are mandatory deliverables. They prove the bug exists without fixing it.

Write unit tests that demonstrate the bug. The test should FAIL with current code:

import pytest

@pytest.mark.xfail(reason="Bug #123: [brief description of bug]")
def test_bug_reproduction_issue_123():
    """
    Reproduces bug described in #123.

    Expected: [expected behavior]
    Actual: [actual behavior - this test currently FAILS]

    This test will pass once the bug is fixed. The @pytest.mark.xfail
    decorator allows it to stay in the test suite while the bug exists.
    """
    # Arrange
    test_input = create_test_case()

    # Act
    result = process_data(test_input)

    # Assert - this assertion captures the expected behavior
    # The test FAILING demonstrates the bug exists (and xfail marks it as expected)
    assert result == expected_value, f"Expected {expected_value}, got {result}"

Why @pytest.mark.xfail:

• Keeps reproduction test in the suite without causing CI failures
• Prevents test loss if the bug is temporarily forgotten
• CI will PASS when marked test FAILS (bug exists) and FAIL when it PASSES (bug is fixed)
• Serves as regression guard after the bug is eventually fixed

Commit tests with message: test: add reproduction test for [issue-number]

Step 6: Root Cause Analysis

Document the root cause in the GitHub issue:

### Root Cause Analysis

**Immediate Cause**
[Direct reason for the failure]

**Underlying Cause**
[Why the immediate cause occurred]

**Contributing Factors**
- [Factor 1]
- [Factor 2]

**Affected Code**
- `path/to/file.py:123` - [description]
- `path/to/other.py:456` - [description]

**Suggested Fix Direction** (do not implement)
[High-level approach for fixing]

Step 7: Finalize Issue

Update the issue status and ensure all sections are complete. Verify all three deliverables are ready:

### Status
✅ Investigation complete

### Deliverables
- ✅ Reproduction test added (marked with `@pytest.mark.xfail`)
- ✅ Diagnostic logging added with proper format/levels
- ✅ Root cause analysis documented

### Reproduction Steps
1. [Precise step 1]
2. [Precise step 2]
3. [Observe error]

### Root Cause Analysis
[Complete analysis with code paths]

### Affected Code
- `path/to/file.py:123` - [description]
- `path/to/other.py:456` - [description]

### Expected vs Actual Behavior
[What should happen vs what actually happens]

### Suggested Fix Direction
[High-level approach without implementation]

### Related
- Reproduction test: `tests/test_bug_123.py` (marked `@pytest.mark.xfail`)
- Diagnostic logging added in commits: [sha1], [sha2]

Issue Update Pattern

Use mcp__github__issue_write with method: "update" to append findings:

Every significant finding should trigger an issue update:
- New reproduction steps discovered
- Code path identified
- Root cause hypothesis formed
- Hypothesis confirmed/rejected
- Related issues found

Resources

• references/logging-guidelines.md - Log level selection for diagnostic code
• references/issue-template.md - Full issue template structure