Root Cause and CAPA

The step between "we found a bad part" and "we fixed the reason." It is slow, expert work, and the reason it is slow is that the evidence sits in four systems that nobody looks at together.

Two rules govern everything below, and they are the whole character of the skill:

Compute, do not eyeball. Control limits, run rules and group comparisons are calculated in code and the skill interprets the computed result. A claim that a process "was drifting," asserted from looking at a data file, is the first thing a quality manager will test and the fastest way to lose the room.

Rank, do not conclude. The output is candidate causal chains with supporting and contradicting evidence. A confident wrong root cause is worse than a ranked list, because it closes the investigation and the fix fails.

Quick start

→ Assemble the evidence window; VERIFY time alignment first
→ Misaligned? Refuse to correlate. Say which conclusions still survive
→ Run the computed checks: SPC drift, clustering, maintenance correlation, recurrence
→ Build candidate chains, each link carrying its own evidence for and against
→ Rank by evidential strength; name what would confirm and what would kill each
→ Draft the 8D: D1-D5 and D7 populated, D6 and D8 left as placeholders
→ Material implicated? Raise the supplier-caused flag for Chain 5
→ Customer pack: redact as a reviewable diff, approved before anything leaves

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.

Two of these are read raw rather than from the consolidated dataset, and that is deliberate. The historian export because no workbook tab carries a high-frequency sensor trace, and the inspection export because a computed control chart needs the measurement as the gage wrote it, not as the ladder normalized it. On identity — which lot, which work order — the dataset still wins. Read What this dataset is authoritative for in ../../shared/contracts/consolidated-dataset.md.

An NCR with no cited requirement blocks the 8D, the customer pack and the diff, with a pointer back to ncr-writeup. Nonconformance is always against a requirement. The investigation itself proceeds as a draft, per Step 5: ranked candidates and an evidence appendix, labelled draft and blocked from the 8D.

Carry the NCR's open questions forward, never close them by omission. A scope with qty_suspect_is_minimum is printed at least N in D2 and in the customer pack; an escape_possible NCR keeps its shipment check open in D3; a null qty_found stays null with its reason.

Workflow

Step 1 — Assemble the evidence window, and verify the clocks

Align sensor, inspection, production and maintenance data onto one zone-aware timeline around the event.

This is most of the work and the highest-risk step in the skill. Different systems record time differently, some in plant local and some in UTC, some zone-naive. Read the per-source clocks and the measured skew from the ## Plant context block rather than assuming, then confirm against an event visible in two sources.

Where alignment cannot be verified, refuse to correlate and say which conclusions survive anyway — lot clustering, for instance, does not depend on the clocks. Read reference/time-alignment.md.

A join is a join only when the data carries it. A work order is on the timeline as a data join when a record ties it to the lot, the part or the event — a lot number on its row, a receipt against it. A work order the NCR's free text names, with no such record, is on the timeline labelled "per NCR text, not a data join", and every conclusion resting on it says so. Calling three work orders a clean traceability join when the data ties the heat to one of them widens the suspect scope on an assertion, and the scope is the number a customer gets told.

Step 2 — Run the pattern checks, computed

• SPC drift on the relevant characteristic across this run and the ones before it, against computed control limits and run rules
• Clustering by material lot, shift, operator, machine and tool change — each reported against its base rate
• Correlation with a maintenance event, gated on step 1 verifying
• Recurrence, carried forward from the NCR's search at creation

Report checks that came back clean, and separately report checks that could not run. Those are different states. Read reference/pattern-checks.md.

Print every figure from the computation, including the comparisons. The control limits, the measured value, and how many times over the limit it is all come out of the same code and go into the figures block (../../shared/computed-figures.md). Computing a limit in code and then dividing by it from memory is how a correct chart gets a wrong sentence written under it. The prose quotes the block.

The SPC rows are required whenever measurements exist, whatever they show. Five rows in the figures block, every run: centreline, UCL, LCL, the basis (which chart, how many points, which runs), and the run rule checked with its result. They are printed when the process was in control, when the run rule found nothing, and when the finding is thin — "computed, no drift found" is a result, and a chart nobody can see is the claim a quality manager tests first. The only run that omits them is one with no measured characteristic, and that run says so under checks that could not run.

Step 3 — Build candidate causal chains

Each stated as a chain rather than a label — material lot variation → hardness above nominal → tool wear accelerated → dimension drift — with supporting and contradicting evidence attached to each link, because a link with no evidence is where the reasoning is actually weak.

Every link carries its own two lines, For and Against, each citing the source record — not one For and one Against for the whole candidate. A link with nothing under For is named as the weak point of that chain, in those words. The format in reference/8d-and-candidates.md is the required shape, not an illustration.

Step 4 — Rank, and name the discriminating tests

By evidential strength, each candidate carrying what would confirm it and what would kill it. Where two are supported equally, present both — a stated tie is a real finding and it names the test that would settle it.

Two separate lines per candidate, and one line for the whole list. Every candidate has a Confirm test and a Kill test on separate lines, never merged into "confirm or kill by re-measuring". Then, after the ranking, one required line: "Cheapest discriminating test:" naming the single test, across all candidates, that settles the most for the least effort, and which candidates it separates. That line is what turns a ranked list into tomorrow morning's plan.

Step 5 — Draft the 8D

Draft or block is decided by two conditions, and nothing else. The 8D is blocked when, per ../../shared/contracts/ncr.md, the NCR has no cited requirement (requirement_cited null with requirement_not_locatable true), or its approval_state is not approved. State which condition blocked it, and still produce the ranked candidates and the evidence appendix as a draft. In every other case — thin evidence, an unresolved tie, a request to "fill it in completely" — the 8D is produced: D1 to D5 and D7 populated from the evidence, with D4 carrying its ranking and uncertainty, and D6 and D8 as empty structured placeholders, because they need a real-world outcome and a human signature, and a pre-filled D6 is a false record of verification. The same NCR gives the same outcome every run.

D4 keeps its ranking and its uncertainty. Every D5 action names the D4 link it breaks, on the action's own line — "breaks link 2, hardness above nominal, by adding incoming hardness verification". An action that breaks no link, a quarantine or a re-inspection, is not a corrective action: move it to D3 if it is containment, or label it "improvement, not corrective action" and leave it outside D5. D7 is the system-level change — and where the recurrence check found a CAPA that failed, D7 addresses why the earlier fix did not hold. Read reference/8d-and-candidates.md.

Step 6 — Route the signal

Where the leading candidate points at purchased material, emit the supplier-caused flag per ../../shared/contracts/supplier-caused-flag.md. That is the trigger into Chain 5.

A tie for first does not raise the flag. Where the material candidate is tied with another, say so, name the cheapest test that would separate them, and hold the flag until that test runs. A supplier claim is commercially serious, and a tie is not a lead.

When the flag is emitted, stamp determination_made_at and say what it is in one line: "determination_made_at is the middle timestamp of Chain 5's escape-to-RFQ metric; it cannot be reconstructed afterwards." It separates investigation time from the sourcing handoff, and without it the two collapse into one number.

The contract requires evidence_against and competing_candidates even when the determination is confident, so a supplier is never accused on half the picture. It carries its own approval state, because a supplier-caused determination is a commercially significant claim.

Step 7 — Produce the customer-facing pack

The internal 8D holds cost data, other customers' names, supplier identity and internal process detail. The customer version must not.

The redaction pass is a reviewable diff, never a silent filter, and the diff is what the quality owner approves. A recurrence stays in — removing it is misrepresentation, not redaction. Every removal request is recorded in the diff, including the ones refused: who asked, what they asked to remove, and the refusal with its reason. Where the pack is still blocked and no diff exists yet, emit a "Pending redaction log" now with the same entry, so the request and the refusal are on the record before the diff is built. Read reference/redaction.md.

Step 8 — Update the register row, and the Quality Register

ncr-writeup wrote this NCR's row in the Quality Register. This step adds what only the investigation knows, per ../../shared/contracts/quality-register-record.md: the 8D step reached, the leading cause labelled as a candidate, the supplier-caused flag, and the effectiveness-check date once one is committed. Per ../../shared/live-dashboard.md, which names every tool call:

1. Find the register — the ## Dashboards line on the Open work page, then the exact title "<Site>: Quality Register".
2. Read the row keyed <site>_<ncr_ref> and carry forward every field this skill does not own. The escape clock, containment and recurrence belong to ncr-writeup; blanking them on a rewrite is how a register loses the one deadline that matters. No row yet (the NCR was written elsewhere): create it from the NCR this skill was handed.
3. set the row, list the collection, rebuild the register in code and publish it.
4. Report it with the dashboard line and the sensitivity line, or the fallback and "The Quality Register was not updated: [reason]."

The row carries references, never content. The NCR and the 8D appear as their identifiers and a one-line summary. Nothing from the internal 8D's cost data, and nothing from the redacted customer pack, goes into the register. The supplier signal stays on the Supply Chain page; the register carries only the flag.

Approval gates

The source NCR's own approval_state gates anything customer-facing. Per ../../shared/contracts/ncr.md, if the NCR isn't approved, block the 8D, the customer-facing pack, and the redaction diff — the investigation itself may still proceed as a draft, since evidence-gathering doesn't need to wait on the NCR's sign-off, but nothing built on an unapproved finding goes further than that.

A supplier-caused determination needs a human owner. It says a vendor caused a defect and it starts a search for an alternate source. The flag carries approval_state, and supplier-quote-request blocks on anything not approved.

Nothing customer-facing leaves without review of the redaction diff. This is Chain 2's closing gate. The pack is drafted and handed to a person; it is never sent.

The investigation itself writes nothing back to any system of record. The 8D is a document the quality owner files.

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.

Report depth follows the plant's preference. The ## Plant context block's Report depth line is summary-first or full (absent means full). Summary-first puts a short summary — what was found, what it affects, what happens next — above the full document; it moves nothing out and drops nothing. Every required field is still in the document below it.

Ranked candidate root causes — each a chain, with For and Against per link citing the source, a separate Confirm test and Kill test, and after the list the one cheapest discriminating test.

The drafted 8D in the plant's or the customer's controlled template captured during onboarding. Per ../../shared/artifact-style.md, a controlled document is never house-styled.

Evidence appendix — the aligned timeline with its verified skew and residual uncertainty, the computed SPC view, the lot analysis, the checks that came back clean, the checks that could not run, and every source file cited.

The figures block — required, and part of the appendix. Every limit, mean, ratio, count and cluster share stated anywhere in the output, with the computation it came from. A claim that something is absent — no prior NCR, no maintenance event in the window — carries the query that returned nothing. Per ../../shared/computed-figures.md. It stays on the internal side of the redaction diff.

Supplier-caused flag — when applicable.

Customer-facing redacted pack, plus the diff — when requested. The diff, or the pending redaction log while the pack is blocked, records every removal request and every refusal.

The register row — per ../../shared/contracts/quality-register-record.md, with its key <site>_<ncr_ref> and the 8D fields, in the reply's summary table on every run, stored or not.

The Quality command-center page: the Quality Register — open corrective actions, carrying the NCR and the 8D by reference, updated in place per ../../shared/live-dashboard.md. Nothing is written to a system of record. It is reported as updated only when the publish returned a URL in this run; otherwise the page is offered in the conversation with "The Quality Register was not updated: [reason]." Never "shared." Read ../../shared/command-center.md. This closes Chain 2, and is one of the two pages Chain 5 produces from one run (the other, Supply Chain, is supplier-quote-request's).

Edge cases and failure modes

• The sensor export does not cover the event window — say so. Do not reason from adjacent data as if it were the event.
• Timestamps misaligned across systems — detect and refuse to correlate. The highest-risk failure mode here, and a spurious correlation stated confidently is worse than no answer.
• Evidence supports two candidates equally — present both. Do not break the tie artificially.
• No prior history exists — say so. Absence of recurrence is not evidence of a one-off, and no_searchable_history is never read as a first occurrence.
• The NCR's cited requirement is missing — block, with a pointer back to ncr-writeup.
• The finding is subjective — no measured characteristic, so the SPC check cannot run. Skip it and say why rather than substituting an impression.
• Clustering on small numbers — three failures split two-to-one is not a pattern. Say that plainly.
• Clustering by operator — name the pattern, not the person. An investigation that terminates on an individual has usually stopped one question early.

Degradation

Runs on exports alone. Sensor and inspection data reach the plugin as scheduled files in every plant; that is the designed path.

If Limble isn't included, or no CMMS connector is live — minor here. Maintenance history arrives in the same scheduled export as everything else, through data-consolidate, and the maintenance-correlation check runs on it unchanged. What changes is freshness: name maintenance explicitly as an export-sourced input in the evidence appendix rather than letting it read as live, since a repair logged after the last export will not be on the timeline at all.

Chain position

Chain 2, inspection to CAPA — step 2, from ncr-writeup. The chain closes on the 8D and its redacted customer pack.

Chain 5, supplier escape to alternate source — step 2, emitting the flag that triggers supplier-quote-request.

Metric. CAPA closure time; first-pass yield.

This skill's investigation time sits inside Chain 5's first segment. That chain measures escape detected → supplier-caused determination → RFQ issued, and the middle timestamp is this skill's to stamp: record when the supplier-caused determination is made, at the moment the flag is raised for approval.

That middle stamp is easy to omit and impossible to reconstruct afterwards, and without it the investigation time and the sourcing handoff collapse into one undifferentiated number — which would hide the half the plugin actually moves.

Reference files