| name | diagnose-fault |
| description | Work from symptoms plus captured readings to ranked causes and next checks, including faults that set no trouble code. |
| allowed-tools | Read, Write, WebSearch, WebFetch |
Diagnose a fault
For the case decode-dtcs does not cover: a symptom with no code, or a code
whose obvious cause has already been eliminated. Most driveability complaints
never set a code.
Inputs
- The symptom, in the driver's words. Ask for it verbatim rather than
translating it early. "Hesitates pulling away when cold" carries information
that "rough running" throws away.
- Snapshots and drive logs in
readings/.
vehicle.json, and service_history in particular.
Steps
-
Characterise the symptom before touching data. Ask, in one batch:
- When: cold start, warm idle, under load, at a steady speed, braking, turning?
- How long has it been happening, and is it getting worse?
- What changed just before it started — fuel fill, a service, a wash, a
pothole, weather?
- Is a warning light on, and steady or flashing? (A flashing MIL means an
active misfire that can destroy a catalytic converter — say so immediately
and advise against continuing to drive.)
That last question about "what changed" resolves a large fraction of cases on
its own, and it is the one people volunteer last.
-
Check the service history before the sensor data. A symptom that began
the week after a service points at the service. This costs one file read and
is skipped constantly.
-
Read fuel trims in context. Long-term trim is the ECU telling you what it
has been compensating for. Positive at idle and normal at load suggests
unmetered air after the MAF; positive across the range suggests fuel delivery
or a MAF reading low. Both need FUEL_STATUS closed loop and a warm engine to
mean anything — see ${CLAUDE_PLUGIN_ROOT}/reference/pids.md.
-
Ask for a targeted drive log if a snapshot cannot settle it. State which
PIDs and under what conditions. "Log RPM, load, MAF and both bank-1 trims for
ten minutes including one motorway pull in third" is an actionable request;
"get more data" is not.
-
Rank causes with a basis and a next check, same rules as decode-dtcs.
Order by cost of elimination, not just by likelihood — a five-minute check
that rules out a whole branch comes before a likelier cause that needs the
car on a lift.
-
Be explicit about the boundary. Generic OBD-II sees emissions-related
powertrain data. If the symptom is in brakes, suspension, steering, ABS,
airbags, transmission or electrics, say the data cannot see it and what tool
could — rather than producing an answer from the powertrain data that happens
to be available.
-
Write it up as a DTC report (dtcs/<ISO8601>-report.json) with
symptoms_reported populated and findings[].code omitted where there is no
code, or as a narrative note in docs/ if the structured form does not fit.
Either way it lands in the repo — a diagnosis held only in a chat is lost.
When to stop and send it to a workshop
Say so plainly, early, and once:
- Flashing MIL, or any misfire under load.
- Loss of braking or steering assistance, a brake warning, or a fluid leak.
- Overheating, oil pressure warning, or a charging warning that is not the
battery.
- Airbag or SRS light.
- Any diagnosis that has converged on something requiring the car to be lifted
or the fuel system opened.
The value here is narrowing the problem before the workshop visit, not avoiding
it. A precise "it is one of these two things, and here is the drive log" is worth
real money at the counter; an amateur repair of a safety system is not.
Data storage
Writes to dtcs/ and docs/ in the workspace repo. Never edits readings/.
Notes
Record the eliminations as carefully as the conclusion. Diagnosis is mostly
elimination, and the eliminations are what the diff does not carry.
