1. User describes the task
2. You read the relevant files to understand the call site and surrounding code
3. ← run preflight here, while thinking
4. Adjust the plan based on findings
5. Write the code

LOCI MCP server is not connected. Please run

/mcp

in Claude Code to manage MCP servers, then approve the loci server. If it does not appear, restart Claude Code — the plugin registers it automatically on startup.

state/project-context.json

{
  "compiler": "...",
  "build_system": "...",
  "architecture": "...",
  "loci_target": "...",
  ...
}

LOCI session context not found. Please restart Claude Code so the plugin setup runs and detects the project environment.

system-reminder

Target: <target>, Compiler: <compiler>, Build: <build>
LOCI target: <loci_target>

undefined

.o

-c

.o

1. If a previous

   .o

   exists for the source file, save it as

   .o.prev

   (this enables delta reporting in Step 3).
2. Compile only the relevant source file with

   -c

   . Always include

   -g

   to emit DWARF debug info (required by asm-analyze):

   <compiler> -g <flags> -c <source> -o <basename>.o

3. Validate the .o — a standalone

   -c

   compile can exit 0 yet produce an empty object file when the source is wrapped in

   #if

   /

   #ifdef

   guards whose defines (

   -D

   ) were not on the command line. After compiling, run:

   <asm-analyze-cmd> extract-symbols --elf-path <basename>.o --arch <loci_target>

   If the result shows 0 symbols or returns an error mentioning "no code" or "preprocessor", the target function was compiled out. Fall back to the secondary path below.

.o

-c -g

.o

.o.prev

.o

.o

undefined

mcp__loci__get_assembly_block_exec_behavior

• csv_text

  : the chunk

• architecture

  : the

  timing_architecture

  field from the output above

• Happy path =

  execution_time_ns

  -

  std_dev

• Worst path =

  execution_time_ns

  +

  std_dev

• Energy =

  energy_ws

  (report in uWs; convert from Ws by multiplying by 1e6)

.o.prev

diff_pct = ((post_value - pre_value) / pre_value) * 100

• Missing declarations: are callees present in the binary with the expected signatures? If a callee is absent, flag a missing forward declaration or linkage issue.
• Indirect calls: any

  bl

  to a register in a callee's CFG — flag as a potential CFI hazard.
• Recursion/cycles: back edges in the CFG with no visible exit condition — flag unbounded recursion.
• Latency: use the MCP timing results above; flag any callee whose worst path violates a timing budget, or where the cumulative hot-path chain exceeds a known deadline.
• Energy: use the MCP energy results above; flag any callee or hot-path chain whose energy cost is notably high relative to the use case (e.g., battery-powered device, ISR context, tight power budget).

• What is this function's role in the system — is it on a hot path, ISR, periodic task, or called once? This determines whether any timing delta is critical, advisory, or irrelevant.
• If

  .o.prev

  exists: is

  |delta| < std_dev

  ? If yes — change is within measurement noise, treat as stable. If

  |delta| > std_dev

  — change is real; flag it. If no

  .o.prev

  : this is the first measurement — record these numbers as the baseline and note no prior exists for comparison.
• Does std_dev indicate a stable path or high hardware variance — and why (cache sensitivity, branch misprediction, pipeline stalls visible in CFG)?
• Is a timing budget known from the session context? If yes, compare hot-path worst against it and flag if exceeded. If no budget is known, report the number and skip the fit assessment.
• What does the CFG structure explain about the timing — which blocks dominate, are there expensive paths the new code will always hit?
• Is the hot-path energy distribution balanced across callees, or does one callee dominate? If dominated, that callee is the leverage point — plan to cache its result, call it less frequently, or substitute a lighter alternative.
• Do any CFG findings (indirect calls, recursion, missing declarations) change the design — does the plan need a guard, a different callee, or a linkage fix?

stack-depth

• Execution context is ISR, HWI, or interrupt callback, AND call chain depth > 3 levels visible in CFG, OR
• Recursion already flagged in CFG analysis above, OR
• Plan adds a new RTOS task (xTaskCreate, Task_construct, osThreadNew) that needs stack sizing, OR
• Plan introduces large local variables on stack (buffers, arrays, C++ objects with non-trivial constructors), OR
• Plan adds a known-deep callee (printf, snprintf, crypto, TLS functions).

• Does worst-case stack depth fit the task's or ISR's configured stack budget?
• Are there large frames that could move to static or heap allocation?
• Does any frame in the chain add cost the plan can eliminate?
• Could the call chain be flattened to reduce depth? → adjust plan based on conclusion before proceeding.

memory-report

• The plan introduces significant new static allocations (large buffers, global arrays, static structs) visible from reading the source, OR

• .o.prev

  exists and the plan grows or restructures existing data sections.

• Does the new allocation fit within available ROM/RAM headroom? (answerable only if map file was provided — memory_regions shows usage %; without map file, report section size delta only)
• Which region is under most pressure after the change?
• Does the plan need to reduce static footprint before proceeding? → adjust plan based on conclusion before proceeding.

• Reasoning identified a lighter or safer alternative callee worth evaluating
• A flagged callee (timing violation, CFI hazard, recursion) has a named alternative visible in the source files already read
• Hot-path energy is dominated by one callee that may have a lighter variant
• The plan for the new function changed (different call sequence, new callees introduced) and those callees have not yet been measured by LOCI — re-query with the new callee set before finalizing the plan

• The plan is stable (no new callees to evaluate and no unresolved flags), OR
• All remaining flags are ✗ BLOCK (require user decision, not further querying), OR
• The cycle limit is reached.

• A missing forward declaration → add it as a step before the function edit
• An unbounded loop in a callee → plan to add a termination guard or budget
• A callee timing violation → plan to cache the result, call asynchronously, or choose a lighter alternative before committing to the design
• An energy concern → plan to batch calls, use a lighter alternative, or move work off the hot path

<venv-python> <plugin-dir>/lib/loci_stats.py record --skill preflight --functions <N> --mcp-calls <M> --co-reasoning <R>

<venv-python> <plugin-dir>/lib/loci_stats.py summary

─── LOCI · preflight ───────────────────
  <N> functions · <M> MCP calls · <R> co-reasoning
    escalated: <skills>                ← omit if no escalation
    <cumulative-summary-output>        ← omit if empty
────────────────────────────────────────

• N = unique callee functions whose assembly was sent to LOCI
• M = MCP calls to

  mcp__loci__get_assembly_block_exec_behavior

  (exec-behaviors)
• R = co-reasoning: 1 for the initial LOCI result pass, +1 for each re-query loop iteration, +2 for each escalated skill (stack-depth, memory-report) — 1 at trigger, 1 when reasoning over results
• escalated = space-separated list of skills called (e.g.

  stack-depth · memory-report

  ); omit the line entirely if no escalation occurred