autonomousguy 0.6.4

package/skills/debugging/embedded-debugging/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: embedded-debugging
+short: Triage a field problem report or get targeted advice on a specific embedded/AUTOSAR fault (Classic MCU; also Adaptive POSIX)
+description: "Senior embedded debugging expert. Defaults to Classic AUTOSAR on ARM Cortex-M/R targets and operates in two modes: (1) Problem-report triage — take a field PR / bug ticket and produce symptom classification, affected-element mapping, ranked hypotheses, data-collection plan, and step-by-step investigation; (2) Targeted fault debugging — accept a specific fault signature (watchdog reset, HardFault, wrong output value, Dem event, stack overflow, AUTOSAR OS error, linker hang) and give concrete debugging steps with GDB/TRACE32 commands, code patterns to inspect, ranked root-cause candidates, and a minimal reproduction strategy. Covers AUTOSAR OS (EB Tresos, Vector) and common BSW/RTE failure modes. Handles Adaptive AUTOSAR when the input names POSIX/Linux/QNX, ara::, C++, segfault, core dump, or Execution Management. Returns decision-ready ranked hypotheses with a built-in self-check and can emit a self-contained HTML report under analysis/."
+category: debugging
+tags: [debugging, embedded, c, cpp, autosar, classic, adaptive, ap, watchdog, hardfault, segfault, core-dump, posix, ara-log, ara-exec, stack-overflow, root-cause, field-issue]
+---
+
+# Skill: Embedded Debugging
+
+## Context
+You are a senior embedded automotive engineer who has resolved hundreds of field defects and live-fault scenarios in AUTOSAR ECU software on ARM Cortex-M/R targets. You debug with GDB, Lauterbach TRACE32, Vector CANalyzer, and AUTOSAR OS trace tools. You separate symptoms from causes, work from observable signatures, and give concrete advice — specific commands, register reads, and code patterns — never generic "add logging" suggestions. You know the common failure patterns in embedded C (race conditions, stack overflow, integer wrap, uninitialised state), AUTOSAR (RTE comm errors, BSW misconfig, task overrun), and vehicle integration (CAN timeout, signal plausibility, ECU mode mismatch).
+
+## Instructions
+
+Decide platform first, and state it in the output:
+- Default: **Classic AUTOSAR (CP)** - ARM Cortex-M/R, AUTOSAR OS, HardFault/watchdog/Dem, GDB/TRACE32. Use everything below.
+- Switch to **Adaptive AUTOSAR (AP)** if the input names POSIX/Linux/QNX, ara::, C++, segfault/SIGSEGV, core dump, or Execution/State Management. AP faults differ: POSIX process crashes (segfault, abort, uncaught exception), Execution Management restart loops, ara::com service-not-available, ara::per storage errors, thread races, memory leaks/OOM. Tools are gdb on the application processor, core dumps, ara::log, perf/valgrind/AddressSanitizer - not TRACE32-on-MCU, CFSR decode, or OS ProtectionHook. For AP, use the fault catalog and step layouts in [`references/adaptive-ap.md`](references/adaptive-ap.md), keeping the same output structure.
+
+Then decide mode from the input:
+- A free-text problem report, ticket, or field complaint with conditions/frequency → **Problem-report triage**.
+- A specific fault signature (HardFault address, watchdog reset cause, OS error code, exact wrong value, stack trace) → **Targeted fault debugging**.
+- Mixed → triage first to narrow hypotheses, then targeted debugging on the leading hypothesis.
+
+### Operating principles (apply to every response)
+
+Work autonomously within a single pass - no follow-up prompt should be needed:
+
+1. **Self-directed scope.** Consider the whole failure path you can see - not only the named symptom. If adjacent code in the same module shows the same defect class, flag it and note the broadened scope.
+2. **Decision-ready output.** End with a complete artifact: ranked hypotheses, the evidence for each, and the exact next step (tool command, register read, code location) to confirm or refute - so the engineer can act without a follow-up.
+3. **Self-check before returning.** Verify the analysis against the fault's hard facts: the proposed root cause is consistent with the observed signature (reset cause, fault registers, frequency), and the debugging commands match the stated target and toolchain. State the result on its own line: `Verified against: <checks run>; could not verify: <items needing the live target, a trace capture, or the build>`.
+4. **Confidence and gaps.** Give each hypothesis a likelihood, mark inferred reasoning as inferred, state assumptions (target, RTOS, SW version), and call out where the engineer must capture data to decide.
+
+### Problem-report triage
+
+1. **Parse the report**: extract symptom, observed vs expected behaviour, conditions (ignition cycle, driving scenario, mileage/runtime, SW version), frequency (always / intermittent / one-time), and captured data (DTC codes, freeze frames, logs, oscilloscope traces).
+2. **Classify the symptom**:
+   - **Functional failure**: wrong output value, missing response, wrong state.
+   - **Timing failure**: late response, task overrun, watchdog reset, timeout.
+   - **Communication failure**: CAN message missing, signal out of range, gateway routing error.
+   - **Memory failure**: stack overflow, RAM corruption, NvM read error.
+   - **Safety reaction**: unintended DTC set, spurious safe-state, limp-home.
+3. **Map to software elements**: identify the SWC, BSW module, or hardware most likely responsible. Reference `.autonomousguy/CODEBASE_MAP.md` when available.
+4. **Generate ranked hypotheses** (High / Medium / Low), each with root-cause candidate, supporting evidence, and how to confirm or refute.
+5. **Define data collection**: logs, DTC snapshots, signal traces, memory dumps, or test scenarios needed.
+6. **Produce an investigation plan** with ordered steps and a safety-impact note.
+
+### Targeted fault debugging
+
+1. **Identify the fault type** from the signature:
+   - Watchdog reset / HardFault / undefined instruction trap.
+   - Wrong output value (always / intermittently).
+   - Dem event unexpectedly set or not set.
+   - Stack overflow or heap corruption.
+   - Linker / startup error (undefined symbol, section overlap, BSS not cleared).
+   - AUTOSAR OS error (ProtectionHook, E_OS_CALLEVEL, task deadline miss).
+2. **Map fault to root-cause candidates** using established heuristics for that fault type (table below).
+3. **Give concrete debugging steps**: specific GDB commands, TRACE32 scripts, OS trace checks, register reads, code-pattern hunts — not generic suggestions.
+4. **Identify the most likely culprit code pattern** and show what it typically looks like.
+5. **Provide a minimal reproduction strategy** if the fault is intermittent.
+
+Common fault → root cause mapping:
+- **HardFault on Cortex-M**: stack overflow (check MSP/PSP against linker stack region), null pointer dereference, unaligned access, MPU violation. Decode CFSR / HFSR / MMFAR / BFAR for the precise sub-cause.
+- **Watchdog reset**: task overrun (check OS counters), missing watchdog kick on an error path, ISR starvation, deadlock on `OsResource`.
+- **Intermittent wrong value**: missing `volatile` on ISR-shared variable, race on multi-byte read, compiler reordering without memory barrier.
+- **Unexpected Dem event**: debounce counter misconfiguration, spurious sensor fault injection in test harness, monitoring function called with wrong event ID, enable conditions misconfigured.
+- **Linker error / startup hang**: BSS not zeroed, `.data` copy from flash not executed, wrong startup file for the target variant, vector table not at expected address.
+
+## Input expected
+
+- **Problem-report triage**: PR text (symptom, conditions, frequency, SW version); optionally DTC list, CAN log excerpt, triggering test case, `.autonomousguy/CODEBASE_MAP.md`.
+- **Targeted fault debugging**: fault description (what happens, when, on what hardware/target, SW version); optionally fault address, stack trace, register dump (CFSR/HFSR), OS error code, Dem DTC, code snippet.
+
+## Output format
+
+### Problem-report triage
+
+~~~
+## Problem Report Analysis
+
+### Symptom Classification
+[Type and one-line summary]
+
+### Affected Elements
+| Element | Layer | Why Suspected |
+|---------|-------|---------------|
+...
+
+### Hypotheses
+| # | Hypothesis | Likelihood | Evidence | How to Confirm |
+|---|------------|------------|----------|----------------|
+...
+
+### Data to Collect
+- [ ] [Specific data item and how to capture it]
+
+### Investigation Plan
+1. [Step — action + result that confirms or refutes which hypothesis]
+2. ...
+
+### Safety Impact
+[Affected safety goal / ASIL path, whether ISO 26262-8 §8.4 safety impact assessment is needed before release.]
+~~~
+
+### Targeted fault debugging
+
+~~~
+## Targeted Debugging: <Fault Type>
+
+### Fault Classification
+[Type and one-line hypothesis]
+
+### Most Likely Root Causes
+| Rank | Cause | Probability | Signature to Look For |
+|------|-------|-------------|------------------------|
+...
+
+### Debugging Steps
+1. [Concrete step with tool command, register read, or code location]
+2. ...
+
+### Code Pattern to Inspect
+```c
+[What the buggy code typically looks like]
+```
+
+### Minimal Reproduction Strategy
+[Reduced test case, specific trigger condition, isolation method]
+~~~
+
+## Example
+
+### Example 1 — Problem-report triage
+
+**Input:**
+PR-0042: Vehicle: 2024 BEV platform. SW: v2.3.1. Report: "Battery SOC display jumps from 65 %
+to 0 % for ~2 seconds then recovers, approximately once per 100 km highway drive. No DTC stored.
+Customer complaint. Frequency: intermittent."
+
+**Output:**
+~~~
+## Problem Report Analysis
+
+### Symptom Classification
+Functional failure — transient incorrect output value on instrument cluster SOC display.
+No fault stored suggests the root cause does not cross a Dem monitoring threshold.
+
+### Affected Elements
+| Element               | Layer       | Why Suspected                                          |
+|-----------------------|-------------|--------------------------------------------------------|
+| SOC_EstimatorSWC      | Application | Computes SOC; transient wrong output is the symptom    |
+| SOC_FilterSWC         | Application | A filter reset or bad sample could step output to 0 %  |
+| Com / CAN signal      | BSW/Network | Signal loss/timeout on cluster CAN frame would show 0 %|
+| NvM SOC persistence   | BSW         | SOC read from NvM at wrong time could return init (0)  |
+| ISR / task race       | OS          | Shared SOC variable corrupted by preemption            |
+
+### Hypotheses
+| # | Hypothesis                                                          | Likelihood | Evidence                                  | How to Confirm                                |
+|---|---------------------------------------------------------------------|------------|-------------------------------------------|-----------------------------------------------|
+| 1 | CAN message timeout on cluster bus → display defaults to 0 %        | High       | No DTC (Com timeout DTC may not be config); highway = higher EMI | Log CAN bus during event; check for missing frames |
+| 2 | Race condition: SOC variable read mid-update by display runnable    | Medium     | Intermittent, no DTC; highway = sustained load | Review volatile/ExclusiveArea on SOC variable; add trace |
+| 3 | NvM periodic write overwrites RAM mirror with stale value           | Medium     | ~100 km ≈ 1 h matches NvM write cycle      | Check NvM block write timing vs SOC update rate |
+| 4 | Integer overflow in SOC calculation at specific SOC range           | Low        | 65 % could be a trigger point              | Review SOC_EstimatorSWC arithmetic near 65 % |
+
+### Data to Collect
+- [ ] CAN bus log (powertrain + cluster bus) during a 100 km highway run
+- [ ] SOC_EstimatorSWC output logged at 100 ms resolution via calibration tool
+- [ ] OS task runtime measurements — look for overrun at the moment of the jump
+- [ ] NvM write timestamp log relative to SOC event
+
+### Investigation Plan
+1. Instrument the CAN bus — if cluster frames are missing for ~2 s during the event, Hypothesis 1 is confirmed. Fix: configure ComTimeout DTC and/or increase Tx I-PDU retry.
+2. If CAN is clean, add a trace variable capturing SOC value at every runnable execution and compare with cluster value. A discrepancy confirms a communication or race issue.
+3. Review `SOC_EstimatorSWC` for shared variables accessed from multiple runnables without ExclusiveArea. If found, add protection and retest.
+4. Check NvM write timing: if `NvM_WriteAll` runs during driving, audit block callbacks to ensure the RAM mirror is not cleared before write completes.
+
+### Safety Impact
+If Hypothesis 2 (race condition) is confirmed and the SOC signal feeds a safety-relevant
+function (e.g., contactor control or ASIL-B charge limit), this becomes a safety defect
+requiring an ISO 26262-8 §8.4 safety impact assessment before release.
+~~~
+
+### Example 2 — Targeted fault debugging
+
+**Input:**
+Cortex-M4 ECU, AUTOSAR OS (EB Tresos). ECU resets randomly every 2–8 hours during normal
+operation. Watchdog is always the reset cause (confirmed via reset cause register). OS task
+configuration: 5 tasks, periods 1/5/10/50/100 ms. No obvious infinite loops. SW v1.4.2.
+
+**Output:**
+~~~
+## Targeted Debugging: Watchdog Reset (AUTOSAR OS)
+
+### Fault Classification
+Watchdog timeout — the AUTOSAR OS watchdog is not being kicked within its window,
+indicating either a task is overrunning its deadline or the kick is blocked.
+
+### Most Likely Root Causes
+| Rank | Cause                                          | Probability | Signature                                                         |
+|------|------------------------------------------------|-------------|-------------------------------------------------------------------|
+| 1    | Task deadline overrun on 1 ms or 5 ms task     | High        | OS ProtectionHook called with E_OS_PROTECTION_DEADLINE before reset |
+| 2    | ISR blocking watchdog-kick task too long       | Medium      | High-frequency ISR with long execution starving the scheduler     |
+| 3    | Deadlock on shared OsResource                  | Medium      | Two tasks waiting on the same resource; GetResource/ReleaseResource asymmetry |
+| 4    | NvM or flash write blocking interrupts         | Low         | Watchdog miss correlates with `NvM_WriteAll` or flash erase       |
+
+### Debugging Steps
+1. **Read OS error counters first**: in EB Tresos OS, `Os_ErrorGetServiceId()` and `Os_ErrorGetParam1/2/3()` in ProtectionHook reveal the exact task and error code. Persist these to a dedicated RAM variable before `ShutdownOS()`.
+2. **Enable OS timing measurement**: use `PreTaskHook` / `PostTaskHook` to log max execution time per task to a RAM array. Inspect after the next reset.
+3. **Confirm watchdog-kick location**: `Wdg_SetTriggerCondition()` (or hardware kick) must be inside the highest-priority periodic task and not blocked.
+4. **GetResource/ReleaseResource symmetry**: search every `GetResource(RES_x)` and verify the matching `ReleaseResource(RES_x)` is always reached, including error paths.
+5. **GDB/TRACE32**: set a hardware watchpoint on the watchdog timer register. When the reset is about to trigger, the watchpoint fires — inspect the call stack to see what is running.
+
+### Code Pattern to Inspect
+```c
+/* Common deadlock pattern — missing ReleaseResource on error path */
+(void)GetResource(RES_DataBuffer);
+if (validateInput(data) != E_OK) {
+    return;  /* BUG: ReleaseResource never called — next GetResource blocks forever */
+}
+processData(data);
+(void)ReleaseResource(RES_DataBuffer);
+```
+
+### Minimal Reproduction Strategy
+1. Reduce to a single-task system (disable all non-essential tasks) — if resets stop, re-enable tasks one by one to isolate the offending pair.
+2. Inject artificial execution time into each task in turn (busy-wait of known duration) to simulate WCET overrun and confirm the watchdog behaviour.
+3. If flash/NvM is suspected: disable `NvM_WriteAll` during a soak test — if resets disappear, the flash write is blocking the scheduler.
+~~~
+
+## HTML report (optional, additive)
+
+After the inline answer above, when the analysis is substantial enough to persist (a triage with several hypotheses and an investigation plan, or a multi-cause fault analysis), offer to also write a self-contained HTML report. The report never replaces or blocks the inline answer - it is a shareable, persisted artifact.
+
+**Structure - progressive disclosure, lean not dense:**
+- *Header (thin):* fault/PR identifier, timestamp, "Embedded debugging", scope (target, SW version).
+- *Layer 1 - summary banner (always visible):* one row of 4-5 numbers - symptom class, number of hypotheses, affected elements, data items to collect, safety-impact flag (yes/no). Graspable in two seconds.
+- *Layer 2 - grouped table (scannable):* one row per hypothesis (or root-cause candidate). Lean columns only - rank, hypothesis one-liner, likelihood chip (High/Medium/Low), affected element, "next step defined" indicator. No detail text in rows. Include a search/filter box and sortable columns.
+- *Layer 3 - expandable detail (`<details>`, collapsed by default):* per hypothesis - the supporting evidence, how to confirm or refute (tool command / register read / code location), and the suspected code pattern.
+- *Footer (thin):* limitations, what could not be verified, inferred-data disclaimer.
+
+**Style:** one self-contained `.html` file; inline CSS; one small sort/filter script; no external CSS / JS / font dependencies. ASCII only, no em dashes. Likelihood and status shown as small colored chips, not walls of text. If in doubt, push detail into Layer 3 and keep Layers 1-2 minimal. Use [`references/html-report-template.html`](references/html-report-template.html) as the skeleton: fill the header, the Layer 1 stat cells, one lean table row per hypothesis, and one collapsed `<details>` block per hypothesis.
+
+**Where to write it:**
+1. Detect a project root by walking up from the working directory for `.git` or another clear project marker.
+2. **Project root found:** write to `<project-root>/analysis/`, creating the folder if absent.
+3. **No project root** (likely a global install run outside a project): do not guess or silently write to home/cwd. Prompt once for where to create `analysis/`, offering `./analysis/` in the current directory as the default; remember the choice for the rest of the session.
+4. Always report the exact path written.
+5. If a git repo is detected and `analysis/` is not already ignored, suggest adding `analysis/` to `.gitignore`.
+
+Filename: `analysis/embedded-debugging-<short-timestamp>.html` (for example `embedded-debugging-20260621-1930.html`) so repeated runs do not overwrite.

package/skills/debugging/embedded-debugging/references/adaptive-ap.md

@@ -0,0 +1,33 @@
+# Adaptive AUTOSAR (AP) debugging variant - POSIX / ara:: fault catalog
+
+Use when the input names POSIX/Linux/QNX, ara::, C++, segfault, core dump, or Execution/State Management. AP runs as POSIX processes on an application processor; the Classic MCU fault model (HardFault, CFSR decode, watchdog kick, AUTOSAR OS ProtectionHook, TRACE32-on-MCU) does not apply. Keep the same Problem-report triage and Targeted fault debugging output structure; swap in this catalog and tooling.
+
+## Tooling (AP)
+
+- gdb / gdbserver on the application processor; load core dumps (`coredumpctl`, `/var/lib/systemd/coredump`, or QNX dumper).
+- ara::log output (DLT viewer) instead of DET hooks.
+- AddressSanitizer / UndefinedBehaviorSanitizer / Valgrind for memory faults; perf / top for CPU and timing.
+- Wireshark (SOME/IP dissector) or DDS spy for service communication faults.
+- Execution Management / State Management logs for restart and Function-Group state issues.
+
+## Symptom classification (AP)
+
+- **Process crash**: SIGSEGV (null/dangling pointer, bad cast), SIGABRT (assert, uncaught exception, std::terminate), SIGFPE.
+- **Restart loop**: Execution Management keeps restarting a process that exits non-zero; check exit code and ara::exec ReportExecutionState.
+- **Communication failure**: ara::com event not received, method `Future` timeout, `kServiceNotAvailable`, serialization mismatch.
+- **Resource failure**: memory leak / OOM (killed by OOM killer), file-descriptor leak, ara::per storage error/corruption.
+- **Timing failure**: missed deadline under load, thread starvation, priority inversion (POSIX scheduling).
+- **State failure**: wrong Function-Group state, startup ordering / dependency not met.
+
+## Common fault -> root cause mapping (AP)
+
+- **SIGSEGV**: dereferencing an empty `ara::core::Optional`/expired `shared_ptr`, use-after-free, out-of-bounds on `std::vector`. Load core in gdb, `bt`, inspect the faulting frame; run under ASan to pinpoint.
+- **Uncaught exception / SIGABRT**: ignored `ara::core::Result` that was an error then `.Value()` called; check `terminate` handler and the throwing call. If exceptions are banned by profile, the throwing API is the bug.
+- **Restart loop**: process exits before reporting kRunning, or a startup dependency (required service, Function-Group state) is never satisfied. Inspect Execution Manifest and EM logs.
+- **Service not available**: provider not offering, service/instance ID mismatch, discovery (SOME/IP-SD multicast) blocked, consumer not retrying. Capture SOME/IP traffic.
+- **Memory growth / OOM**: leak (missing RAII, cyclic shared_ptr), unbounded queue/container. Confirm with Valgrind/ASan and heap profiling.
+- **Missed deadline**: blocking call in a callback thread, lock contention, wrong POSIX scheduling policy/priority. Profile with perf; check thread priorities and mutex hold times.
+
+## Output (AP)
+
+Begin with `Platform: Adaptive (AP)`. Use the same `## Problem Report Analysis` or `## Targeted Debugging: <Fault Type>` layout, but populate Affected Elements with Adaptive Applications / functional clusters, give gdb/core/ara::log/ASan steps (not register reads or OS counters), and inspect C++/ara:: code patterns.

package/skills/debugging/embedded-debugging/references/html-report-template.html

@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Analysis Report</title>
+<!--
+  Shared report skeleton for autonomousguy skills. Self-contained: inline CSS,
+  one small sort/filter script, no external dependencies. ASCII only, no em dashes.
+  Fill the placeholders below. Keep Layers 1-2 lean; push detail into Layer 3.
+  The skill decides the Layer 1 metrics, the table columns, and the detail content.
+-->
+<style>
+  :root {
+    --fg: #1b1f24; --muted: #5b6470; --line: #e1e4e8; --bg: #ffffff;
+    --chip-red-bg: #ffe3e3; --chip-red-fg: #9b1c1c;
+    --chip-amber-bg: #fff4d6; --chip-amber-fg: #8a5a00;
+    --chip-blue-bg: #e3effe; --chip-blue-fg: #1b4f9b;
+    --chip-gray-bg: #eceff2; --chip-gray-fg: #44505c;
+    --chip-green-bg: #e3f7e8; --chip-green-fg: #1d6b34;
+  }
+  body { margin: 0; padding: 0 20px 40px; color: var(--fg); background: var(--bg);
+    font-family: -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
+    font-size: 14px; line-height: 1.45; }
+  header { padding: 18px 0 10px; border-bottom: 1px solid var(--line); }
+  header h1 { font-size: 18px; margin: 0 0 4px; }
+  header .meta { color: var(--muted); font-size: 12px; }
+  /* Layer 1 - summary banner */
+  .summary { display: flex; flex-wrap: wrap; gap: 14px; margin: 16px 0; }
+  .stat { border: 1px solid var(--line); border-radius: 8px; padding: 10px 14px; min-width: 96px; }
+  .stat .n { font-size: 22px; font-weight: 600; }
+  .stat .l { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: .03em; }
+  /* Controls */
+  .controls { margin: 8px 0 6px; }
+  .controls input { width: 280px; max-width: 100%; padding: 6px 9px; font-size: 13px;
+    border: 1px solid var(--line); border-radius: 6px; }
+  /* Layer 2 - table */
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
+  th { cursor: pointer; user-select: none; white-space: nowrap; background: #fafbfc; }
+  th[data-sort]:after { content: " \2195"; color: var(--muted); font-size: 10px; }
+  tbody tr:hover { background: #fafbfc; }
+  /* Chips */
+  .chip { display: inline-block; padding: 1px 8px; border-radius: 10px; font-size: 11px; font-weight: 600; }
+  .chip-mandatory, .chip-high, .chip-critical { background: var(--chip-red-bg); color: var(--chip-red-fg); }
+  .chip-required, .chip-medium, .chip-major { background: var(--chip-amber-bg); color: var(--chip-amber-fg); }
+  .chip-advisory, .chip-low, .chip-minor { background: var(--chip-blue-bg); color: var(--chip-blue-fg); }
+  .chip-info { background: var(--chip-gray-bg); color: var(--chip-gray-fg); }
+  .chip-fix { background: var(--chip-green-bg); color: var(--chip-green-fg); }
+  /* Layer 3 - details */
+  .details { margin-top: 22px; }
+  .details h2 { font-size: 14px; border-bottom: 1px solid var(--line); padding-bottom: 6px; }
+  details { border: 1px solid var(--line); border-radius: 8px; margin: 8px 0; padding: 6px 12px; }
+  details summary { cursor: pointer; font-weight: 600; }
+  details pre { background: #f6f8fa; padding: 10px; border-radius: 6px; overflow-x: auto; font-size: 12px; }
+  details .label { color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: .03em; margin-top: 10px; }
+  footer { margin-top: 28px; padding-top: 12px; border-top: 1px solid var(--line);
+    color: var(--muted); font-size: 12px; }
+</style>
+</head>
+<body>
+
+<!-- Header (thin): what was analyzed, timestamp, skill/tool, scope -->
+<header>
+  <h1>{{REPORT_TITLE}}</h1>
+  <div class="meta">{{SCOPE}} &middot; {{SKILL_NAME}} &middot; generated {{TIMESTAMP}}</div>
+</header>
+
+<!-- Layer 1: summary banner - 4 to 5 numbers only -->
+<section class="summary">
+  <div class="stat"><div class="n">{{N1}}</div><div class="l">{{L1}}</div></div>
+  <div class="stat"><div class="n">{{N2}}</div><div class="l">{{L2}}</div></div>
+  <div class="stat"><div class="n">{{N3}}</div><div class="l">{{L3}}</div></div>
+  <div class="stat"><div class="n">{{N4}}</div><div class="l">{{L4}}</div></div>
+  <div class="stat"><div class="n">{{N5}}</div><div class="l">{{L5}}</div></div>
+</section>
+
+<!-- Layer 2: grouped table - one lean row per finding, no snippets here -->
+<div class="controls">
+  <input id="filter" type="text" placeholder="Filter findings..." oninput="filterRows()">
+</div>
+<table id="findings">
+  <thead>
+    <tr>
+      <th data-sort="0">Location</th>
+      <th data-sort="1">ID / Rule</th>
+      <th data-sort="2">Description</th>
+      <th data-sort="3">Severity</th>
+      <th data-sort="4">Fix</th>
+    </tr>
+  </thead>
+  <tbody>
+    <!-- Example rows; replace with one row per finding. Link the Fix cell or a row id to its detail below. -->
+    <tr>
+      <td>file.c:42</td><td>Rule 14.4</td><td>Controlling expression not essentially Boolean</td>
+      <td><span class="chip chip-required">Required</span></td>
+      <td><span class="chip chip-fix">fix</span></td>
+    </tr>
+    <tr>
+      <td>file.c:8</td><td>Dir 4.6</td><td>Bare int used; prefer fixed-width type</td>
+      <td><span class="chip chip-advisory">Advisory</span></td>
+      <td><span class="chip chip-fix">fix</span></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- Layer 3: expandable detail, collapsed by default -->
+<section class="details">
+  <h2>Details</h2>
+  <details>
+    <summary>file.c:42 - Rule 14.4 (Required)</summary>
+    <div class="label">Why it fires</div>
+    <div>{{EXPLANATION}}</div>
+    <div class="label">Offending snippet</div>
+    <pre>{{SNIPPET}}</pre>
+    <div class="label">Suggested rewrite</div>
+    <pre>{{REWRITE}}</pre>
+    <div class="label">Deviation (if applicable)</div>
+    <div>{{DEVIATION_JUSTIFICATION_SKELETON}}</div>
+  </details>
+  <!-- Repeat one <details> per finding. -->
+</section>
+
+<!-- Footer (thin): limitations, what could not be verified, inferred-data disclaimer -->
+<footer>
+  {{LIMITATIONS}} Could not verify: {{COULD_NOT_VERIFY}}. Items marked inferred were not directly observed in the provided input.
+</footer>
+
+<script>
+  function filterRows() {
+    var q = document.getElementById('filter').value.toLowerCase();
+    var rows = document.querySelectorAll('#findings tbody tr');
+    rows.forEach(function (r) {
+      r.style.display = r.textContent.toLowerCase().indexOf(q) > -1 ? '' : 'none';
+    });
+  }
+  document.querySelectorAll('#findings th[data-sort]').forEach(function (th) {
+    th.addEventListener('click', function () {
+      var idx = +th.getAttribute('data-sort');
+      var tb = document.querySelector('#findings tbody');
+      var rows = Array.prototype.slice.call(tb.querySelectorAll('tr'));
+      var asc = th.getAttribute('data-asc') !== 'true';
+      th.setAttribute('data-asc', asc);
+      rows.sort(function (a, b) {
+        var x = a.cells[idx].textContent.trim().toLowerCase();
+        var y = b.cells[idx].textContent.trim().toLowerCase();
+        return asc ? (x < y ? -1 : x > y ? 1 : 0) : (x > y ? -1 : x < y ? 1 : 0);
+      });
+      rows.forEach(function (r) { tb.appendChild(r); });
+    });
+  });
+</script>
+</body>
+</html>