Breakdown Diagnosis skill

Breakdown Diagnosis

A machine is down. Every minute it stays down, the plant is not producing — and the largest component of MTTR is usually not the repair, it is working out what is wrong.

The technician has five sources of evidence available and time to assemble none of them. That gap is this skill.

Quick start

→ Capture the event: asset, time down, symptom, fault codes
→ SAFETY FIRST: if there is a safety implication, that leads. Always
→ Pull the sensor window; read shapes, not just threshold breaches
→ Mine maintenance history and the free-text close-out notes
→ Read the photos; consult the manual's troubleshooting tree
→ Rank candidate causes: evidence, cheapest discriminating test, expected fix
→ Cite the specific prior work orders behind each candidate
→ Draft the PM interval change that would stop it recurring
→ Emit the downtime record for the next production report

---

Safety leads. Always.

Where a failure has a safety implication, surface it first — before any diagnosis. Never let a diagnostic suggestion precede a safety flag.

Every diagnosis opens with this line, flagged or not: "Follow your plant's lockout procedure before anyone works on this machine. This is not a safety assessment." A false flag never removes it, and no step sends anyone to the machine above it.

A technician reading a ranked list of likely causes is already reaching for tools. If the honest answer is "this guard is defeated" or "that is a stored energy hazard," it has to arrive before the thing that sends them toward the machine, not underneath it.

This is a done-when condition, and it is the one non-negotiable ordering rule in the skill.

What counts as a safety implication. Set safety_flagged: true when the evidence shows any of these, and write which one, with its evidence, in safety_reason:

• a seized or locked rotating part: spindle, chuck, bar feeder, conveyor
• a defeated, bypassed or failed guard or interlock
• stored energy: springs, counterweights, a part under load, a raised axis
• hydraulic or pneumatic pressure that has to be bled before work
• an electrical fault: a trip, a burnt smell, exposed or damaged wiring
• a fault that was cleared by restarting rather than fixed ("ran off and restarted"), now repeating

When none of these is shown, the flag is false and safety_reason says "none of the safety triggers shown". Never set the flag on a feeling, and never leave it off because the diagnosis is uncertain: an uncertain stored-energy hazard is a safety implication.

---

Inputs

First, find the plant setup: from the task's own folder (never cd into the plugin), run python3 -I <this skill's folder>/../../shared/scripts/plant_setup.py find, do its setup_page_first step, then read the profile at profile_path and any rate at rates_path, per ../../shared/replies.md.

Input	Source	Form
The breakdown event	User report, or a maintenance work order	Conversation / CMMS connector or maintenance export
Asset record and specs	CMMS	CMMS connector, else the asset register export
Maintenance history and close-out notes	CMMS	CMMS connector, else the maintenance export
Current PM plan for the asset	CMMS	CMMS connector
Sensor window around the failure	Historian export to M365, scheduled or on-demand	CSV
Technician photos	M365, or uploaded in conversation	Images
Manufacturer's manual	M365 document library	PDF
Production context — what was running	data-consolidate output, or a direct MES export	../../shared/contracts/consolidated-dataset.md

---

Workflow

Step 1 — Capture the event

Asset, time it went down, the symptom as the technician describes it, and any fault codes the machine is showing. Take their words; do not translate a symptom into a cause at capture.

Step 2 — Pull the sensor window

A configurable period before the failure. Read excursions, trends and step changes, not just threshold breaches — a vibration reading that climbed for six hours without ever crossing its alarm limit is a bearing failing in plain sight.

Verify the window covers the event. If it does not, say so and do not reason from adjacent data as if it were the event.

Step 3 — Mine the maintenance history and close-out notes

Weight recency and symptom similarity. Search this asset, then siblings of the same model — a new machine with no history is not a dead end.

Run both searches as queries, in code, and keep what they returned. One filter on this asset's ID, one across every asset of the same model on the symptom's own words. The work orders each query returned go into the figures block (../../shared/computed-figures.md) by number. "This asset has eleven prior records" and "the sister machine has no bearing history" are both claims about a query result, and both have been wrong when written from memory: a count is printed from the filter, and an absence names the filter that came back empty.

Then run the template check, every time, before any note is cited. Group every close-out note in the history by its exact text, and for each group count the distinct assets and the distinct makes and models it appears on. The model comes from the asset name where the asset record has no model column, and the output says so. The grouped result goes in the figures block. Then:

• Same text on assets of different makes is a template — a default the technician clicked, not an observation about this machine. It is shown, labelled "same text on N assets — not specific to this machine", may be mentioned as a fleet-wide pattern, and is never cited as this machine's evidence for any candidate.
• The same failure recurring on siblings of the same model is exactly what the sibling search is for: cite it as a fleet pattern for that model, with the work orders named.
• A note that appears once is this asset's evidence, and is cited.

Skipping this check is how two runs on the same data cite two different sets of work orders. With it, the cited set is a function of the data.

The free-text close-out notes are the highest-value input here and the least used anywhere. Read reference/evidence-sources.md for how to mine them and how to report their coverage honestly.

Step 4 — Read the photos

Visible damage, leaks, wear, part numbers on the failed component, readings on the machine's own display. Describe what is visible; never assert a diagnosis from an unclear image.

Step 5 — Consult the manual

Match the fault code and symptom to the manufacturer's troubleshooting tree, and cite the page. A manufacturer's stated tolerance beats an inference.

Step 6 — Rank candidate causes

Ordered by likelihood. Each one carries three things:

1. The evidence supporting it, from the sources above
2. What to check first — the cheapest and fastest test that would discriminate between this candidate and the next one
3. The expected fix, and the repair path

That second item is the one that saves time. Ranking three causes is useful; naming the five-minute check that eliminates two of them is what shortens MTTR.

Every candidate is written under the same three sub-headings, in this order: Evidence / First check / Expected fix and repair path. Fixed headings, every candidate, including the leading one. A candidate whose Expected fix is missing shows an empty heading, which a reader can see; the rerun found the leading candidate silently lacking one while candidate 2 had it, and a fixed shape is what stops that.

Step 7 — Cite the specific prior work orders

Behind each candidate, the actual work order numbers and close-out notes, so the technician can read what was done last time rather than taking a ranked list on trust.

A candidate with no citation is a guess and is labelled as one. Not omitted — an experienced hunch is worth stating — but marked as reasoning rather than evidence.

Step 8 — Propose the PM plan adjustment

Once a diagnosis lands, the specific interval or procedure change for that asset and that failure mode, drafted for the maintenance planner.

If a bearing failed from misalignment at 1,400 hours, the interval or the procedure should probably change. This almost never happens today, because the person diagnosing is not the person who owns the PM schedule. Closing that loop is the reactive-to-proactive step and it is core behaviour, not an extra.

Without the current PM plan this degrades to a recommendation that first asks what today's interval is. The step stays either way.

Pricing the stoppage. Where someone asks what the downtime cost, resolve the downtime cost per hour per ../../shared/secret-config.md, Resolving a rate — MFG_DOWNTIME_COST_PER_HOUR if set, then a confirmed rate in the plant profile, then a placeholder there, labelled — multiply hours by it, and show it as an internal figure with its source. Where neither route holds one, report minutes and hours, name the rate and both ways to set it, and stop — see Edge cases. Never reach for an industry figure.

Step 9 — Batch mode: the bad actor ranking

Run across all assets instead of one incident, ranked by total downtime minutes and by failure frequency. A different question from "what is wrong with this machine right now," which is why it is a mode here rather than a separate report.

Read reference/bad-actor-mode.md.

---

Approval gates

Everything this skill produces is a draft the technician or planner applies. Nothing is written back to any system of record.

A CMMS connector's write scope is not assumed — Limble's, the worked example, is not confirmed in its public setup guide — so this is designed for read-only and treats write as an upgrade rather than an assumption. Concretely:

• Never update a maintenance ticket automatically. The diagnosis is output the technician applies.
• Asked to close out or update the ticket, write the close-out note as a labelled draft. Say it never writes to a system of record — and, where no CMMS connector is live, say that too — then produce the note itself: what was found, what was done, what to watch, in the words a technician would put in the close-out field. "Paste it into the ticket if it is right" with nothing to paste hands the work back. Never offer to close it later. Per ../../shared/command-center.md.
• The PM adjustment is a draft for the planner, who owns that schedule.
• The diagnosis stays advisory until a technician confirms it. Its downtime record carries that state explicitly, so the production report cannot present an unconfirmed cause as established.

---

Output

Every document this skill produces is printed in the reply, in full. Saving a copy to a file as well is fine, as Word or Excel per ../../shared/replies.md, never .txt; a file instead of the reply is not. The person reads the reply, and every delimited block and outbound check lives in it — a document only on disk has been neither seen nor checked. A record handed to another skill is saved and summarised, never pasted as raw YAML; memory blocks are written where the plant's memory lives; and the name on an approval is asked, never taken from the account. All three per ../../shared/replies.md.

Ranked candidate causes — evidence, what to check first, expected fix, repair path.

Cited history — the specific prior work orders and close-out notes behind each candidate.

Sensor observation summary — what the data showed in the failure window, plainly stated, including when it showed nothing.

The figures block — required whenever the output states a count, a duration, a ratio or an absence. Every record count, every "N of M notes were usable," and every "no history found" appears here with the query behind it, and the prose quotes it. Per ../../shared/computed-figures.md. An absence found by a document search is reported as not found by search, never as does not exist.

PM plan adjustment proposal — drafted for the planner.

The downtime record — per ../../shared/contracts/downtime-record.md, in exactly the shape daily-production-report consumes with no transformation between. Note in particular that an ongoing outage carries a null duration rather than zero, and that safety_flagged travels with it.

Bad actor ranking — in batch mode.

The Operations command-center page, maintenance section — the diagnosis and its current status, produced as an artifact you place. Nothing is written to a system. Read ../../shared/command-center.md. Chain 4's other half, folding the diagnosis into the next production report's downtime log, happens on daily-production-report's side of the handoff.

Rendered in the house artifact style (../../shared/artifact-style.md) when the output is something the technician will refer back to.

---

Edge cases and failure modes

• No sensor data for this asset — very common; most assets are not instrumented. Proceed on history, notes, photos and the manual, and say clearly that sensor evidence was unavailable. This is the normal run, not a degraded one.
• The sensor export does not cover the failure window — say so. Do not reason from adjacent data.
• A new asset with no history — fall back to the manual and to sibling assets of the same model. State which.
• Close-out notes are terse or useless — "fixed," "repaired," "OK now." Report the coverage honestly rather than over-reading them.
• Photos are ambiguous — describe what is visible and name what cannot be told apart from the image.
• A safety-critical failure — the safety implication leads, before any diagnosis.
• Evidence supports two candidates equally — present both. Do not break the tie artificially.
• Asked what the downtime has cost, with no rate on file — say the rate is not set in either route, name MFG_DOWNTIME_COST_PER_HOUR and the plant profile ("update our downtime cost"), and report the downtime in minutes and hours. No dollar-per-hour figure of any kind appears: not a typical one, not a range, not an example of what not to use. A benchmark named in order to reject it is still the number that gets used. Per ../../shared/secret-config.md.

---

Degradation

If no CMMS connector is live (the default: Limble and other CMMS systems are added through custom-connector) — this is the skill most affected. Without Limble or any CMMS connector, it reads the maintenance export.

What is lost: live asset records, open maintenance work orders, and the current PM plan.

What survives, and it is the important part: maintenance history including the free-text close-out notes, because those are a field on the work order record and export cleanly. The notes are the highest-value input in the skill, so its core reasoning is intact.

What actually changes is freshness. A breakdown is a real-time event and a nightly export is not. Diagnosing a machine that went down twenty minutes ago means the most recent — and often most relevant — tickets are not in the data yet. Say so rather than letting the history look current.

Three mitigations, all built, because any one recovers most of the value:

1. An on-demand export the technician can trigger before the run.
2. Pasted or uploaded work orders for that asset.
3. A spoken description of recent work in conversation. "We were in there last Tuesday for the same thing" is real evidence.

The PM adjustment step degrades to a recommendation that first asks what the current interval is. It stays in the skill either way.

---

Chain position

Chain 4, Breakdown to next report — step 1, feeding daily-production-report. The chain pauses at step 4 by nature, because that step is a human working a physical machine, and the diagnosis is advisory throughout.

Metric. Mean time to repair.

---

Reference files

File	Load when
reference/evidence-sources.md	Steps 2 to 5 — the five sources, how to read each, and the citation rule
reference/bad-actor-mode.md	Step 9 — the batch ranking and its coverage traps
../../shared/computed-figures.md	Step 3 and on emit — the figures block, and how to state an absence
../../shared/contracts/downtime-record.md	On emit — the exact shape daily-production-report consumes