/proxiblue-skills:workflow-investigate-bug Skill

/proxiblue-skills:workflow-investigate-bug

Forensic investigation. Read-only. Produces an evidence-backed root-cause analysis document; doesn't fix.

Per the mandatory investigation protocol in ~/claude-skills-central/rules/investigation.md: enumerate own blast radius first, read ALL failure artefacts (not a sample), compare to prior passing state, only THEN form a hypothesis. This workflow makes that protocol concrete.

Inputs

Ask user for:

Ticket number (optional but recommended for output naming + GH cross-link)
Bug description — what's broken, observed behaviour
Expected behaviour — what should happen instead
Reproduction URL / steps — at least one path that reliably reproduces

Pre-flight

Confirm DDEV web container context (hostname && pwd).
Verify pb-codegraph reachable: mcp__pb-codegraph__list_repos returns non-empty. If down, fall back to grep but warn output is shallower.
Verify Playwright present: which yarn && test -d tests/m2-hyva-playwright.
Verify clean working tree (git status --short). If dirty, refuse — investigation needs a known-good base to diff against.

Visible todo list

1. Capture environmental facts (branch, commit, recent migrations, container uptime)
2. Reproduce the bug with Playwright + record video, screenshots, console, network
3. Scan var/log/ for errors in the reproduction window
4. Identify affected files from the reproduction (network requests, log file paths, error stack traces)
5. For each affected symbol, mcp__pb-codegraph__impact → enumerate callers / dependents
6. git log + git blame on the affected files — identify candidate regression commits
7. For each candidate regression commit, summarise the diff + correlation to the bug
8. [OPTIONAL] If security implications suspected: invoke /proxiblue-skills:workflow-security-audit on the affected scope
9. Rank candidate root causes by evidence strength
10. Write the investigation doc to .claude/investigations/<ticket>-<YYYYMMDD>.md
11. Recommend handoff workflow (build-feature / hotfix / escalate)

Step details

Step 1 — environment snapshot

echo "Branch:           $(git rev-parse --abbrev-ref HEAD)"
echo "Commit:           $(git rev-parse HEAD) ($(git log -1 --format='%cd' --date=short))"
echo "Composer status:  $(composer diagnose 2>&1 | head -5)"
echo "DDEV uptime:      $(uptime)"
echo "Recent migrations: $(bin/magento setup:db:status 2>&1 | tail -5)"
echo "Cache state:      $(bin/magento cache:status 2>&1)"

Save to investigation log. This is the "WHAT I CHANGED THIS SESSION" / context from the investigation protocol.

Step 2 — Playwright reproduction

First, review the client's evidence. If the ticket has a screen recording (.mov/.mp4/.webm), you cannot skip it — it shows the exact click-path and failure state. Download it and extract frames with ffmpeg (installed in the web container), then Read the frames — see github-analysis Step 1b for the exact commands (gh issue view … | grep the asset URL → curl → ffmpeg -vf fps=1). Let the observed path drive the reproduction spec below.

Write a spec at tests/m2-hyva-playwright/src/apps/<APP_NAME>/tests/_investigations/<ticket>-repro.spec.ts that:

Navigates to the reproduction URL
Captures full-page video (use video: 'on')
Screenshots at each step (page.screenshot())
Captures console messages (page.on('console', msg => ...))
Captures network requests (page.on('request', ...) + page.on('response', ...))
Captures uncaught exceptions (page.on('pageerror', err => ...))
Asserts the BROKEN state (test should currently fail / show the bug)

Run it: cd tests/m2-hyva-playwright/src/apps/<APP_NAME>/ && yarn playwright test _investigations/<ticket>-repro.spec.ts. Capture all artifacts (video, screenshots, trace).

If reproduction fails to fire the bug → flag the bug as "non-reproducible in current env" + document conditions tried. STOP — can't investigate what we can't reproduce.

Step 3 — log scan

Scan logs for the reproduction window:

WINDOW_START="$(date -d '5 minutes ago' '+%Y-%m-%d %H:%M:%S')"
for log in var/log/system.log var/log/exception.log var/log/debug.log var/log/payment.log; do
  echo "=== $log ==="
  [ -f "$log" ] && awk -v start="$WINDOW_START" '$0 >= start' "$log" 2>/dev/null | tail -30
done

Plus docker exec ddev-<project>-web grep -i "<keyword from bug>" /var/log/php-fpm.log if needed.

Extract: error messages, stack traces, file:line references, any class names mentioned.

Step 4 — identify affected files

From the network requests + stack traces, derive a list of PHP files involved. For URL-based: trace through app/code/*/etc/routes.xml → controller class. Trace controller → models → blocks → templates.

For each: also check if there are recent commits touching it.

Step 5 — pb-codegraph impact propagation

For each affected symbol, run mcp__pb-codegraph__impact <symbol>. The returned callers/dependents are part of the "blast radius" — bugs are often in callers passing wrong input, not in the called code.

Annotate the investigation: which callers exist; which were recently modified.

Step 6 — git log + blame on affected files

git log --oneline -10 -- <affected-file>
git blame <affected-file> | grep -v "^\^"   # filter root commits

For files with recent activity → fetch the commits' diffs:

git show <sha> -- <file>

Step 7 — diff correlation

For each candidate commit identified by blame/log:

Summarise WHAT changed
Cross-reference to the bug symptom (does the diff plausibly cause the observed behaviour?)
Rank: strong / moderate / weak correlation

Step 8 — security audit (optional chain)

If the bug involves auth bypass, data leakage, unauthorised actions, or unusual log entries:

/proxiblue-skills:workflow-security-audit --diff-against=live

Captures whether the bug has security implications beyond the reported behaviour.

Step 9 — rank candidate root causes

For each candidate root cause, score evidence:

Reproduction confirms behaviour matches hypothesis (high)
Log entries cite the suspect file/method (high)
Recent commit on the suspect file changed something related (high)
Impact analysis shows untouched indirect callers (medium — possible)
Suspect file unchanged in 6+ months (low — bug is probably environmental/data-side)

Step 10 — investigation doc

Write to .claude/investigations/<ticket>-<YYYYMMDD>.md. Follow the mandated failure-report format from ~/claude-skills-central/rules/investigation.md:

# Investigation: <ticket> — <one-line bug summary>

Date: <YYYY-MM-DD>
Investigator: Claude (workflow-investigate-bug)

## WHAT I CHANGED THIS SESSION (from git diff)
- No production code changes; investigation is read-only.
- Added Playwright reproduction spec: tests/m2-hyva-playwright/src/apps/<APP_NAME>/tests/_investigations/<ticket>-repro.spec.ts

## WHAT THE ARTEFACTS SHOW
- Reproduction video: <path to .webm>
- Reproduction screenshots: <paths>
- Console errors: <verbatim lines>
- Network failures: <verbatim>
- var/log/system.log:NN: <verbatim line>
- var/log/exception.log:NN: <verbatim line>

## COMPARE TO PRIOR RUN
- Bug NOT reproducible on commit <sha> (last passing state per ticket history)
- Reproducible on commit <sha> (current HEAD)
- Diff between those commits: <list of touched files, link to git compare URL>

## HYPOTHESIS (with evidence)
1. **Strongest:** <claim> — supported by <artefact line/key>
2. Alternative: <claim> — supported by <artefact line/key>

## WHAT I HAVE NOT VERIFIED
- <gap>
- (or "nothing, hypothesis is evidence-complete")

## Impact (from pb-codegraph)
<table or list of affected symbols + their callers>

## Recommended next step
- If the hypothesis is "regression in commit <sha>": invoke /proxiblue-skills:workflow-build-feature for ticket <ticket>; the fix should revert or correct the regression, with tests covering the bug behaviour.
- If "data-side / environmental": stop and escalate (DBA / ops); no code workflow needed.
- If "security implications": investigation findings have been augmented by /proxiblue-skills:workflow-security-audit — see appended section.

Step 11 — handoff recommendation

Print:

============================================================
INVESTIGATION COMPLETE — <ticket>

Doc:            .claude/investigations/<ticket>-<YYYYMMDD>.md
Repro spec:     <path>
Repro artifacts: <video / screenshots paths>

Top hypothesis: <one-line summary>
Evidence:       <one-line summary>

Recommended next:
  /proxiblue-skills:workflow-build-feature <ticket>
    (fix as a feature; reproduction spec becomes the regression test in the test plan)

OR for a known-safe one-line fix without full workflow overhead:
  Apply the fix directly, then /deploy-check live

OR if data/environmental:
  Stop — escalate to DBA / ops, no code workflow appropriate
============================================================

What this skill does NOT do

Does not modify ANY production code. Only adds the reproduction spec (which is test code, not prod).
Does not commit or push.
Does not guess fixes without evidence — adheres to the investigation protocol's "no claim without citation" rule.
Does not skip artefact reading. If reproduction fails or logs unavailable, stops and reports limitations.

Composes well with

/proxiblue-skills:workflow-build-feature — natural next step when the investigation identifies a fix
/proxiblue-skills:workflow-security-audit — auto-chained from step 8 when bug has security implications
The mandatory investigation protocol at ~/claude-skills-central/rules/investigation.md — this skill operationalises that protocol

Agent Skills: /proxiblue-skills:workflow-investigate-bug

Install this agent skill to your local

Skill Files