plan-maintenance

name	plan-maintenance
description	Compute what service work is due or overdue from intervals, history and odometer into a dated plan. Use for "what does the car need".
allowed-tools	Read, Write

Plan maintenance

Turn vehicle.json — intervals, history, odometer — into a plan of what is due, when, and in what order. Arithmetic first, judgement second.

Inputs

• vehicle.json: service_intervals, service_history, odometer, annual_distance_km.
• Recent snapshots, for the condition signals below.

Steps

1. Update the odometer. Ask for the current reading and its date, and write it to vehicle.odometer. Every calculation below depends on it, and a stale figure produces a confidently wrong plan.

2. Compute due state per interval item. For each entry in service_intervals, find the matching most recent service_history entry:

   km_since   = odometer.value - history.odometer_km
   months_since = months(today - history.date)
   due_by_km     = every_km     - km_since
   due_by_time   = every_months - months_since
   

   With whichever: first (the default), the item is due when either hits zero. Convert distance to a date using annual_distance_km so everything can be read on one timeline.

3. State the arithmetic, then the recommendation. Lead with the numbers — "oil: 14,200 km since last change against a 15,000 km interval, 11 months against 12" — before any advice. The numbers are checkable; the advice is not.

4. Handle missing data honestly. Three distinct cases, reported distinctly:

   • No interval recorded → unknown, needs the handbook. Not "due".
   • Interval known, no history → unknown last service date, and say what it would take to establish it (stamped service book, garage invoice, sticker under the bonnet).
   • Both known → a real number.

   Never fill a gap with a typical value and then compute against it. An assumed timing-belt date is the most expensive guess available.

5. Order the output by severity first, then by how overdue. Safety-critical items overdue by a little outrank routine items overdue by a lot.

6. Fold in condition signals from recent readings, as evidence rather than as a schedule:

   • CONTROL_MODULE_VOLTAGE persistently below ~13.5 V with the engine running → charging system worth checking.
   • Long-term fuel trims drifting positive over successive readings → air or fuel delivery degrading; often a filter or a MAF before it becomes a code.
   • Coolant temperature not reaching or not holding normal → thermostat.
   • Rising DISTANCE_W_MIL → a fault has been ignored for a while.

   These are hypotheses from a limited data set, not measurements of the part. Label them as such.

7. Group by visit. Items that share labour — anything needing the same panel off, the same fluid drained, the same lift — are cheaper done together. Say which items those are; that is where the plan earns its keep against a bare list of dates.

8. Write maintenance/plan.md with the dated table and the reasoning, and append to maintenance/log.md when work is completed. When work is done, also add it to service_history in vehicle.json — otherwise the next plan recomputes from the old date and repeats itself. That write-back is the step that gets skipped; do it in the same session as the report.

Data storage

Writes maintenance/plan.md and updates vehicle.json in the workspace repo. Does not write outside the workspace.

Notes

Intervals from a forum or from general knowledge are not this car's schedule. Where service_intervals[].source is anything other than the manufacturer's documentation, carry that caveat into the plan rather than dropping it once the number is in the file.