| name | decode-dtcs |
| description | Expand OBD-II trouble codes into system, subsystem and meaning, and write a DTC report. Use for "what does P0301 mean", "decode codes". |
| allowed-tools | Read, Write, WebSearch, WebFetch |
Decode trouble codes
Turn a raw code into a structured, sourced finding. Writes
dtcs/<ISO8601>-report.json per
${CLAUDE_PLUGIN_ROOT}/schemas/dtc-report.schema.json.
Inputs
- Codes — from a snapshot in
readings/, or typed directly by the user.
vehicle.json — make and engine code decide whether a description is
trustworthy.
Steps
-
Decompose structurally first, from
${CLAUDE_PLUGIN_ROOT}/reference/dtc-codes.md. System, code type, subsystem,
fault index. This needs no lookup and cannot be wrong.
-
Check character 2 before quoting any description.
0 → generic SAE/ISO. The standard description applies to any vehicle;
set description_source: sae_j2012.1, and often 2/3 → manufacturer-specific. A generic description is
likely to be a different manufacturer's code with the same number. Either
find a make-specific source and set description_source: manufacturer, or
say the meaning is not established and set unknown.
Presenting a manufacturer-specific code with a generic description is the
single most common way this kind of work goes wrong, and it is invisible in
the output — the wrong answer is a fluent sentence about a real part.
-
Read the freeze frame for each code from the snapshot. The conditions the
fault set under narrow the cause more than the code text does. A misfire at
high load and a misfire at cold idle are different problems wearing the same
number.
-
Group before ranking. Several codes often share one root cause — a
cluster of lean codes across both banks points upstream of both, and a set of
U codes usually points at one module or a connector, not at each system
named. Record these in correlations.
-
Rank candidate causes for this vehicle, cheapest and most likely first.
Every candidate needs a basis — the PID value, freeze frame, co-occurring
code or model-specific pattern behind it. A cause with no basis is a guess
and does not belong in the list.
-
Give each candidate a next_check: the cheapest test that confirms or
eliminates it. The output is only useful if it says what to do next.
-
Record ruled_out with the reason. The eliminations are what stop the
next session re-treading the same ground, and they are the part that would
otherwise be lost.
-
Weight by status. pending (mode 07) is an early warning or a transient,
not a confirmed fault. permanent (mode 0A) cannot be cleared by any tool and
indicates the ECU still considers the fault live.
-
Say what you could not determine. Put open questions in unresolved,
each paired with the reading that would answer it.
Sourcing
Generic codes: the standard. Manufacturer-specific codes and model-specific
patterns: search, and cite the source in basis. Owner forums are often the
only source of a real-world failure pattern for a specific engine, and are worth
using — but mark forum consensus as such rather than presenting it in the same
voice as the standard.
Data storage
Writes to dtcs/ in the workspace repo. Does not modify anything in
readings/ — snapshots are evidence and stay immutable. If a reading looks
wrong, take another one; do not edit the old one.
Notes
This is diagnostic assistance, not a qualified opinion. Where a code implicates
brakes, steering, airbags or fuel delivery, say so and set drivability
accordingly rather than burying it in a ranked list.
