decode-dtcs

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

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

8. 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.

9. 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.