Back to Details

bug-report

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LOCI Bug Report

LOCI Bug 报告

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."
当LOCI分析失败、skill未调用、结果缺失或无效时生成取证诊断报告。报告将写入带时间戳的
.md
文件，可分享或导入到后续的Claude Code会话中用于问题诊断和修复。
本skill即便在LOCI完全损坏的情况下也必须可正常工作。禁止使用MCP工具，仅可使用：Read、Bash、Glob、Grep。
从LOCI会话上下文（会话启动时的system-reminder区块）读取以下值，并在下方出现占位符的位置进行替换：
  • asm-analyze command: <path>
    → 用作 
    <asm-analyze-cmd>
  • venv python: <path>
    → 用作 
    <venv-python>
  • plugin dir: <path>
    → 用作 
    <plugin-dir>
如果会话上下文中不存在
plugin dir:
，则回退使用
CLAUDE_PLUGIN_ROOT
环境变量。如果两者都不可用，停止执行并告知用户："无法定位LOCI插件目录。请确认插件已安装并重启Claude Code。"

Step 0: Capture user description

步骤0：收集用户问题描述

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?"
本skill接受一个可选的参数字符串用于描述问题，将其存储为
<user-description>
。
如果未提供参数，用一句话询问用户： "你期望LOCI执行什么操作，实际发生了什么？"

Step 1: Collect environment snapshot

步骤1：收集环境快照

Run these in parallel where possible via Bash and Read:
  1. Claude Code version — 
    claude --version 2>/dev/null || echo "unknown"
  2. Claude model — read from the current session context (you know the model name from your system prompt, e.g. "claude-opus-4-6", "claude-sonnet-4-6"). Record the exact model ID.
  3. Plugin version — Read 
    <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".
  4. OS info — 
    uname -a
  5. OS short name — 
    uname -s | tr '[:upper:]' '[:lower:]'
    (for filename)
  6. Project context — Read 
    <plugin-dir>/state/project-context.json
    (full JSON). If missing, record "MISSING".
  7. LOCI paths — Read 
    <plugin-dir>/state/loci-paths.json
    . If missing, record "MISSING".
  8. Setup marker — 
    cat <plugin-dir>/.setup-complete 2>/dev/null || echo "MISSING"
  9. Git info — 
    git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown"
    and 
    git log --oneline -3 2>/dev/null || echo "no git history"
  10. Hooks config — Read 
    <plugin-dir>/hooks/hooks.json
    . If missing, record "MISSING".
尽可能通过Bash和Read并行执行以下操作：
  1. Claude Code版本 — 
    claude --version 2>/dev/null || echo "unknown"
  2. Claude模型 — 从当前会话上下文读取（你可从系统提示中获取模型名称，例如"claude-opus-4-6"、"claude-sonnet-4-6"），记录准确的模型ID。
  3. 插件版本 — 读取
    <plugin-dir>/../../../.claude-plugin/marketplace.json
    （或仓库级别的
    .claude-plugin/marketplace.json
    ），提取
    plugins[0].version
    。如果未找到，尝试读取
    <plugin-dir>/../../marketplace.json
    ，都找不到则回退为"unknown"。
  4. OS信息 — 
    uname -a
  5. OS短名称 — 
    uname -s | tr '[:upper:]' '[:lower:]'
    （用于生成文件名）
  6. 项目上下文 — 读取
    <plugin-dir>/state/project-context.json
    （完整JSON），如果缺失则记录"MISSING"。
  7. LOCI路径配置 — 读取
    <plugin-dir>/state/loci-paths.json
    ，如果缺失则记录"MISSING"。
  8. 安装完成标记 — 
    cat <plugin-dir>/.setup-complete 2>/dev/null || echo "MISSING"
  9. Git信息 — 
    git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown"
    以及 
    git log --oneline -3 2>/dev/null || echo "no git history"
  10. Hooks配置 — 读取
    <plugin-dir>/hooks/hooks.json
    ，如果缺失则记录"MISSING"。

Step 2: Run 12-point diagnostics checklist

步骤2：执行12项诊断检查清单

For each check, record status (PASS / FAIL) and a detail string.
#CheckHow to testPASS when
1MCP tools visibleCheck if 
mcp__plugin_loci_loci__get_assembly_block_exec_behavior
appears as an available tool in the current session		Tool is listed
2Session context exists
<plugin-dir>/state/project-context.json
exists and contains 
project_root
File exists with key
3Compiler detected
compiler
field in project-context.json is not 
unknown
or empty		Has a value
4Architecture detected
architecture
field in project-context.json is not 
unknown
or empty		Has a value
5LOCI target supported
loci_target
in project-context.json is one of: 
aarch64
, 
armv7e-m
, 
armv6-m
, 
tc3xx
Value in set
6Python venv working
<venv-python> --version
exits 0		Exit code 0
7asm-analyze installed
<venv-python> -c "from loci.service.asmslicer import asmslicer"
exits 0		Exit code 0
8Setup complete
.setup-complete
file exists in plugin dir		File exists
9Build artifacts existGlob for 
.loci-build/**/*.o
or any 
.elf
/
.o
/
.axf
in project root		At least one found
10c++filt availableRead 
cxxfilt_dir
from 
loci-paths.json
, run 
<cxxfilt_dir>/c++filt --version
Exit code 0
11session-init executable
test -x <plugin-dir>/hooks/session-init.sh
Exit code 0
12hooks.json valid
<plugin-dir>/hooks/hooks.json
parses as JSON		Valid JSON
If 
<venv-python>
is unavailable, checks 6, 7 automatically FAIL. If 
loci-paths.json
is missing, check 10 automatically FAILs.
对于每一项检查，记录状态（PASS / FAIL）和详细信息。
#检查项测试方式判定通过条件
1MCP工具可见检查当前会话的可用工具列表中是否存在
mcp__plugin_loci_loci__get_assembly_block_exec_behavior
工具在列表中
2会话上下文存在
<plugin-dir>/state/project-context.json
存在且包含
project_root
字段		文件存在且包含指定字段
3检测到编译器project-context.json中的
compiler
字段不是
unknown
或空值		存在有效取值
4检测到架构project-context.json中的
architecture
字段不是
unknown
或空值		存在有效取值
5LOCI目标架构受支持project-context.json中的
loci_target
属于以下值之一：
aarch64
、
armv7e-m
、
armv6-m
、
tc3xx
取值在指定集合内
6Python venv可正常工作
<venv-python> --version
执行退出码为0		退出码0
7asm-analyze已安装
<venv-python> -c "from loci.service.asmslicer import asmslicer"
执行退出码为0		退出码0
8安装流程完成插件目录下存在
.setup-complete
文件		文件存在
9构建产物存在通配符匹配
.loci-build/**/*.o
或项目根目录下任意
.elf
/
.o
/
.axf
文件		至少找到一个匹配文件
10c++filt可用从
loci-paths.json
读取
cxxfilt_dir
，执行
<cxxfilt_dir>/c++filt --version
退出码0
11session-init可执行
test -x <plugin-dir>/hooks/session-init.sh
退出码0
12hooks.json格式合法
<plugin-dir>/hooks/hooks.json
可解析为JSON		格式合法
如果
<venv-python>
不可用，检查项6、7自动判定为FAIL。 如果
loci-paths.json
缺失，检查项10自动判定为FAIL。

Step 3: Collect stats

步骤3：收集统计数据

Run via Bash (skip if venv is broken):
<venv-python> <plugin-dir>/lib/loci_stats.py summary
<venv-python> <plugin-dir>/lib/loci_stats.py global-summary
Record output or "stats unavailable — venv not working".
通过Bash执行以下命令（如果venv损坏则跳过）：
<venv-python> <plugin-dir>/lib/loci_stats.py summary
<venv-python> <plugin-dir>/lib/loci_stats.py global-summary
记录输出内容，或记录"stats unavailable — venv not working"。

Step 4: Reasoning — common failure forensics

步骤4：问题分析 — 常见故障取证

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.
这是最重要的部分。分析会话上下文和诊断结果判断故障原因，采用自由形式的分析内容（不要套模板），确保如实反映当前会话状态。

A. Skill Not Invoked

A. Skill未触发

If the user's issue is that a LOCI skill should have triggered but didn't, investigate:
  1. Prompt match — compare the user's original prompt against the 
    when_to_use
    triggers for each relevant skill. List the trigger keywords from the SKILL.md and note which matched or didn't.
  2. Auto-run conditions — for auto-triggered skills:
    • loci-post-edit
      : Was the edited file a C/C++/Rust source (.c, .cc, .cpp, .cxx, .h, .hpp, .hxx, .rs)? Was an Edit/Write/MultiEdit tool used?
    • loci-preflight
      : Was Claude in 
      /plan
      mode when the user described new logic?
  3. Skill visibility — is the skill listed in the 
    Available:
    line of the session-reminder? If not, session-init may not have registered it.
  4. Deferred tools — check if 
    loci:loci-post-edit
    , 
    loci:loci-preflight
    , etc. appear in the system-reminder deferred tools / available skills list. If absent, the plugin may not be loaded.
  5. Competing behavior — did Claude answer directly instead of invoking the skill? Did another skill or tool pre-empt? Note what Claude did instead.
如果用户的问题是LOCI skill本应触发但未触发，调查以下内容：
  1. Prompt匹配 — 将用户的原始prompt与每个相关skill的
    when_to_use
    触发条件进行比对，列出SKILL.md中的触发关键词，标记哪些匹配、哪些不匹配。
  2. 自动触发条件 — 针对自动触发的skill：
    • loci-post-edit
      ：被编辑的文件是否为C/C++/Rust源文件（.c、.cc、.cpp、.cxx、.h、.hpp、.hxx、.rs）？是否使用了Edit/Write/MultiEdit工具？
    • loci-preflight
      ：用户描述新逻辑时Claude是否处于
      /plan
      模式？
  3. Skill可见性 — skill是否在session-reminder的
    Available:
    行中列出？如果没有，可能是session-init未完成注册。
  4. 延迟工具列表 — 检查
    loci:loci-post-edit
    、
    loci:loci-preflight
    等是否出现在system-reminder的延迟工具/可用skill列表中。如果不存在，可能插件未加载。
  5. 冲突行为 — Claude是否直接回答了问题而没有调用skill？是否有其他skill或工具抢占了执行？记录Claude实际执行的操作。

B. Results Not Evaluated or Not Valid

B. 结果未评估或无效

If a skill ran but produced no results, wrong results, or results that weren't used, investigate:
  1. Compilation — did the compilation step succeed? Look for compiler errors, missing headers, wrong flags. Check if the compiler from project-context.json is actually installed: 
    which <compiler>
    .
  2. asm-analyze output — did 
    extract-assembly
    or 
    extract-cfg
    produce valid JSON? Common failures: function name not found in binary, architecture mismatch between ELF and LOCI target, empty output.
  3. MCP response — did the MCP call return timing/energy data? Common failures: MCP timeout, authentication expired mid-session, server error, empty response. Check if MCP was authenticated at session start (check 1).
  4. Result parsing — were 
    timing_csv_chunks
    , 
    timing_architecture
    , or 
    execution_time_ns
    fields present in the output? If asm-analyze returned data but Claude didn't use it, note the gap.
  5. Delta comparison — for post-edit: did 
    .o.prev
    exist before the recompile? Did 
    diff-elfs
    return 0 changed functions (meaning the binary didn't actually change)?
  6. Output suppression — did Claude generate analysis but fail to present it? (Context window pressure, interrupted response, tool call error.)
如果skill已运行但未产生结果、结果错误或结果未被使用，调查以下内容：
  1. 编译环节 — 编译步骤是否成功？检查是否有编译器错误、头文件缺失、编译参数错误。检查project-context.json中指定的编译器是否实际已安装：
    which <compiler>
    。
  2. asm-analyze输出 — 
    extract-assembly
    或
    extract-cfg
    是否生成了合法JSON？常见故障：二进制文件中未找到函数名、ELF架构与LOCI目标架构不匹配、输出为空。
  3. MCP响应 — MCP调用是否返回了时序/能耗数据？常见故障：MCP超时、会话中途认证过期、服务器错误、响应为空。检查会话启动时MCP是否已完成认证（检查项1）。
  4. 结果解析 — 输出中是否存在
    timing_csv_chunks
    、
    timing_architecture
    或
    execution_time_ns
    字段？如果asm-analyze返回了数据但Claude未使用，记录该断层。
  5. 差异比对 — 针对post-edit场景：重编译前是否存在
    .o.prev
    文件？
    diff-elfs
    是否返回0个变更函数（意味着二进制文件实际未发生变化）？
  6. 输出抑制 — Claude是否生成了分析结果但未展示？（上下文窗口压力、响应中断、工具调用错误。）

C. Root cause

C. 根本原因

Based on the diagnostics and reasoning above, state the root cause. Use the dependency chain to find the most upstream failure:
hooks → setup → venv → asm-analyze → project-context → MCP → compilation → analysis
If all 12 checks pass, the issue is likely:
  • Skill trigger wording mismatch (Claude didn't recognize the intent)
  • Transient MCP timeout
  • A bug in the skill logic itself
基于上述诊断和分析，说明根本原因。按照依赖链查找最上游的故障点：
hooks → setup → venv → asm-analyze → project-context → MCP → compilation → analysis
如果全部12项检查都通过，问题大概率是：
  • Skill触发词不匹配（Claude未识别用户意图）
  • 临时MCP超时
  • Skill逻辑本身存在Bug

Step 5: Write report file

步骤5：生成报告文件

Determine the output filename:
report-<YYYY-MM-DD>-<os-short>.md
Write the file to the current working directory using this structure:
markdown
undefined
确定输出文件名：
report-<YYYY-MM-DD>-<os-short>.md
按照以下结构将文件写入当前工作目录：
markdown
undefined

LOCI Diagnostic Report

LOCI 诊断报告

Generated: <YYYY-MM-DD HH:MM:SS UTC>
生成时间: <YYYY-MM-DD HH:MM:SS UTC>

Versions

版本信息

ComponentVersion
Claude Code<claude --version output>
Claude model<model ID, e.g. claude-opus-4-6>
LOCI plugin<plugin version>
OS<uname -a output>
组件版本
Claude Code<claude --version 输出>
Claude模型<模型ID，例如 claude-opus-4-6>
LOCI插件<插件版本>
操作系统<uname -a 输出>

User Description

用户问题描述

<user-description>
<user-description>

Environment

环境信息

FieldValue
Project root<project_root or cwd>
Git branch<branch>
Compiler<compiler or "unknown">
Build system<build_system or "unknown">
Architecture<architecture or "unknown">
LOCI target<loci_target or "unknown">
MCP status<connected / not authorized>
asm-analyze<command path or "unavailable">
venv python<path or "unavailable">
字段取值
项目根目录<project_root 或当前工作目录>
Git分支<branch>
编译器<compiler 或 "unknown">
构建系统<build_system 或 "unknown">
架构<architecture 或 "unknown">
LOCI目标架构<loci_target 或 "unknown">
MCP状态<已连接 / 未授权>
asm-analyze<命令路径 或 "unavailable">
venv python<路径 或 "unavailable">

Diagnostics Checklist

诊断检查清单

#CheckStatusDetail
1MCP tools visible<PASS/FAIL><detail>
2Session context exists<PASS/FAIL><detail>
3Compiler detected<PASS/FAIL><detail>
4Architecture detected<PASS/FAIL><detail>
5LOCI target supported<PASS/FAIL><detail>
6Python venv working<PASS/FAIL><detail>
7asm-analyze installed<PASS/FAIL><detail>
8Setup complete<PASS/FAIL><detail>
9Build artifacts exist<PASS/FAIL><detail>
10c++filt available<PASS/FAIL><detail>
11session-init executable<PASS/FAIL><detail>
12hooks.json valid<PASS/FAIL><detail>
Result: <N>/12 checks passed.
#检查项状态详情
1MCP工具可见<PASS/FAIL><详情>
2会话上下文存在<PASS/FAIL><详情>
3检测到编译器<PASS/FAIL><详情>
4检测到架构<PASS/FAIL><详情>
5LOCI目标架构受支持<PASS/FAIL><详情>
6Python venv可正常工作<PASS/FAIL><详情>
7asm-analyze已安装<PASS/FAIL><详情>
8安装流程完成<PASS/FAIL><详情>
9构建产物存在<PASS/FAIL><详情>
10c++filt可用<PASS/FAIL><详情>
11session-init可执行<PASS/FAIL><详情>
12hooks.json格式合法<PASS/FAIL><详情>
结果: <N>/12 项检查通过。

Reasoning

问题分析

What the user was trying to do

用户尝试执行的操作

<describe the intent and expected behavior>
<描述用户意图和预期行为>

What should have happened

预期应发生的行为

<which skill should have triggered, with trigger conditions from when_to_use>
<哪个skill应该被触发，以及when_to_use中对应的触发条件>

What actually happened

实际发生的行为

<what Claude did instead — answered directly, wrong skill, error, silence>
<Claude实际执行的操作 — 直接回答、调用了错误的skill、报错、无响应>

Why it failed

故障原因

<root cause reasoning chain, referencing specific checklist failures>
<根本原因推理链，引用具体的检查项失败结果>

Skill trigger analysis

Skill触发分析

<for each relevant skill, did the trigger conditions match?>
<针对每个相关skill，触发条件是否匹配?>

Diagnosis

诊断结论

Root cause: <one-sentence root cause>
Contributing factors: <any additional FAIL checks>
Suggested fix: <numbered actionable steps to resolve>
Root cause: <一句话描述根本原因>
Contributing factors: <其他所有失败的检查项>
Suggested fix: <编号的可执行修复步骤>

Stats

统计数据

Branch stats

分支统计

<loci_stats.py summary output, or "no stats recorded">
<loci_stats.py summary 输出，或 "no stats recorded">

Global stats

全局统计

<loci_stats.py global-summary output, or "no stats recorded">
<loci_stats.py global-summary 输出，或 "no stats recorded">

Raw Data

原始数据

<details> <summary>project-context.json</summary>
json
<full contents or "MISSING">
</details> <details> <summary>loci-paths.json</summary>
json
<full contents or "MISSING">
</details> <details> <summary>hooks.json</summary>
json
<full contents or "MISSING">
</details> <details> <summary>.setup-complete</summary>
<contents or "MISSING">
</details> <details> <summary>Recent git log</summary>
<git log --oneline -3 output>
</details> ```
<details> <summary>project-context.json</summary>
json
<完整内容或 "MISSING">
</details> <details> <summary>loci-paths.json</summary>
json
<完整内容或 "MISSING">
</details> <details> <summary>hooks.json</summary>
json
<完整内容或 "MISSING">
</details> <details> <summary>.setup-complete</summary>
<内容或 "MISSING">
</details> <details> <summary>最近Git提交记录</summary>
<git log --oneline -3 输出>
</details> ```

Step 6: Present summary to user

步骤6：向用户展示摘要

After writing the report file, display a concise summary:
undefined
写完报告文件后，展示简洁的摘要：
undefined

LOCI Diagnostic Summary

LOCI 诊断摘要

<N>/12 checks passed.
Root cause: <one-sentence diagnosis>
Suggested fix: <numbered steps>
Share this file when reporting issues, or open it in a new Claude Code session for further investigation.
─── LOCI · bug-report ───────────────── Report: <absolute-path-to-report-file> ────────────────────────────────────────

The report file path MUST appear in the footer as the last visible output.
Use the absolute path so the user can copy-paste it directly.

Do NOT record stats for this skill (diagnostic/informational only).
Do NOT emit a LOCI voice remark (inappropriate for failure context).
<N>/12 项检查通过。
根本原因: <一句话诊断结论>
修复建议: <编号步骤>
上报问题时可分享本文件，或在新的Claude Code会话中打开本文件做进一步排查。
─── LOCI · bug-report ───────────────── 报告路径: <报告文件绝对路径> ────────────────────────────────────────

报告文件路径必须作为最后可见的输出出现在页脚，使用绝对路径方便用户直接复制粘贴。

禁止为本skill记录统计数据（仅用于诊断/信息采集用途）。
禁止输出LOCI语音提示（不适用于故障场景）。