Forensic diagnostic report for LOCI — collects environment state, runs health checks, and writes a timestamped report when analysis fails or doesn't trigger. Invoke when: "bug report", "LOCI isn't working", "exec-trace didn't run", "skill didn't trigger", "MCP not connecting", "results are wrong", "results missing", "generate diagnostic", "something is broken", "debug LOCI", or any LOCI failure the user wants investigated.
Generate a forensic diagnostic report when LOCI analysis fails, a skill does
not invoke, or results are missing or invalid. The report is written to a
timestamped .md file that can be shared or loaded into a future Claude Code
session to diagnose and fix the issue.
This skill must work even when LOCI is completely broken. Do NOT use MCP tools. Use only: Read, Bash, Glob, Grep.
Read these values from the LOCI session context (system-reminder block at session start) and substitute them wherever the placeholders appear below:
asm-analyze command: <path> → use as <asm-analyze-cmd>venv python: <path> → use as <venv-python>plugin dir: <path> → use as <plugin-dir>If plugin dir: is not in the session context, fall back to the
CLAUDE_PLUGIN_ROOT environment variable. If neither is available, stop and
tell the user: "Cannot locate LOCI plugin directory. Ensure the plugin is
installed and restart Claude Code."
The skill accepts an optional argument string describing the problem.
Store it as <user-description>.
If no argument was provided, ask the user in one sentence: "What did you expect LOCI to do, and what happened instead?"
Run these in parallel where possible via Bash and Read:
claude --version 2>/dev/null || echo "unknown"<plugin-dir>/../../../.claude-plugin/marketplace.json
(or the repo-level .claude-plugin/marketplace.json), extract
plugins[0].version. If not found, try <plugin-dir>/../../marketplace.json.
Fall back to "unknown".uname -auname -s | tr '[:upper:]' '[:lower:]' (for filename)<project-context> path (the per-session
keyed file, listed as project context: in this session's context). Record
the full JSON. If missing, record "MISSING".<plugin-dir>/state/loci-paths.json. If missing,
record "MISSING".cat <plugin-dir>/.setup-complete 2>/dev/null || echo "MISSING"git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown"
and git log --oneline -3 2>/dev/null || echo "no git history"<plugin-dir>/hooks/hooks.json. If missing,
record "MISSING".For each check, record status (PASS / FAIL) and a detail string.
| # | Check | How to test | PASS when |
|---|---|---|---|
| 1 | MCP tools visible | Check if mcp__plugin_loci_loci__get_assembly_block_exec_behavior appears as an available tool in the current session | Tool is listed |
| 2 | Session context exists | <project-context> (keyed file) exists and contains project_root | File exists with key |
| 3 | Compiler detected | compiler field in <project-context> is not unknown or empty | Has a value |
| 4 | Architecture detected | architecture field in <project-context> is not unknown or empty | Has a value |
| 5 | LOCI target supported | loci_target in <project-context> is one of: aarch64, armv7e-m, armv6-m, tc399 | Value in set |
| 6 | Python venv working | <venv-python> --version exits 0 | Exit code 0 |
| 7 | asm-analyze installed | <venv-python> -c "from loci.service.asmslicer import asmslicer" exits 0 | Exit code 0 |
| 8 | Setup complete | .setup-complete file exists in plugin dir | File exists |
| 9 | Build artifacts exist | Glob for .loci-build/**/*.o or any .elf/.o/.axf in project root | At least one found |
| 10 | c++filt available | Read cxxfilt_dir from loci-paths.json, run <cxxfilt_dir>/c++filt --version | Exit code 0 |
| 11 | session-init executable | test -x <plugin-dir>/hooks/session-init.sh | Exit code 0 |
| 12 | hooks.json valid | <plugin-dir>/hooks/hooks.json parses as JSON | Valid JSON |
| 13 | Quota not exceeded | If MCP tools are visible (check 1 passed), call mcp__loci__loci_usage_for_period with from_ts = 24h ago, to_ts = now (UTC ISO). Compare total_tokens against tier limit (free=30000, premium=300000, enterprise=1500000). User plan comes from the MCP response or default to free. | total_tokens < tier_limit |
If <venv-python> is unavailable, checks 6, 7 automatically FAIL.
If loci-paths.json is missing, check 10 automatically FAILs.
If check 1 failed (MCP not visible), check 13 automatically FAILs with "MCP not connected — cannot check quota".
Run via Bash (skip if venv is broken):
<venv-python> <plugin-dir>/lib/loci_stats.py summary --context-file "<project-context>"
<venv-python> <plugin-dir>/lib/loci_stats.py global-summary
Record output or "stats unavailable — venv not working".
This is the most important section. Analyze the session context and diagnostics to determine what went wrong. Write this as free-form reasoning (not templated) so it captures the actual session state.
If the user's issue is that a LOCI skill should have triggered but didn't,