dantotsu

Dantotsu — Defect Analysis

A structured method for turning a single defect into a permanent quality improvement. Originated by Sadao Nomura, a former Toyota engineer, who used it to cut manufacturing defects by up to 98%. Adapted for software, where a small project run fully under this method reached ~0.3 defects per 1,000 lines of code — one to two orders of magnitude below the industry average — without the huge upfront-spec overhead of aerospace-grade processes.

Defect = any unexpected behavior for the user; the gap between the behavior that occurred and the behavior that was expected.

Two principles carry over directly from the manufacturing original and matter more than any specific template:

• Classify by where a defect escaped, not by severity. Severity triage optimizes for "what do we fix first"; stage classification optimizes for "what part of our process is leaking" — which is what actually drives systemic improvement.
• Analyze both occurrence and outflow. Why did the defect happen (prevention), and separately, why wasn't it caught sooner (detection). Conflating the two loses the detection-gap signal, which is usually a process/tooling fix rather than a code fix.
• Check hypotheses against facts, not against how plausible they feel. The main risk in a whys chain isn't lack of expertise — it's the feeling of having understood ("avoir compris") standing in for actually understanding ("comprendre"). Competence in the domain makes this worse, not better: an experienced reader accepts a plausible-sounding cause too quickly precisely because it fits prior experience. Each link in the chain should be checked against something verifiable (the diff, the logs, the ticket history) before moving to the next "why".

Detection stages

Ask the user which stage caught the defect if it isn't already clear — never guess.

Stage	Where it was caught
A	Local environment (dev's own machine)
B	Team level (CI or code review)
C	Validation environment (Product Owner spotted the gap)
D	Qualif/staging environment (QA spotted it)
E	Production (a team member spotted it)
F	Client (client reported it)

Later stages (E, F) are more costly and signal a bigger process gap than earlier ones (A, B).

For recurring or cross-team defects, map the path the behavior or data took, record where the defect was found, and make recurrence visible by stage. Set a measurable improvement target from the current baseline. This adapts Nomura's guidance on mapping quality-information flows, classifying defects by discovery point, and visualizing quality data for software teams (The Toyota Way of Dantotsu Radical Quality Improvement, preview, chapter 1).

Workflow

First check whether the defect is causing ongoing harm. Prioritize containment (hotfix, rollback, or workaround) within the user's authorized scope before the analysis below; do not delay it to complete classification or the whys chain. Record containment already performed separately from proposed actions.

Then work through these analysis steps in order. Pin down the defect and detection stage before drawing root-cause conclusions.

1. Describe the defect. State it as expected behavior vs. actual behavior. If the user hasn't given enough detail to do this precisely, ask — don't assume or invent specifics.
2. Identify the detection stage (A–F above). Ask the user if it isn't stated.
3. Check for recurrence. Ask the user (or check available issue trackers/history if you have access) whether this same defect, or one with the same underlying pattern, has occurred before. Recurring defects point to a deeper systemic root cause and make eradication more important than a one-off fix.
4. Find the root cause with the 5 Whys (occurrence). Start from the defect description in step 1 — not from a symptom or a guess — and ask "why" repeatedly, each time treating the previous answer as the new thing to explain. Stop once the answer describes something concretely actionable (a process gap, a missing check, a wrong assumption), not just another restatement of the symptom. Five is a typical depth, not a hard rule.
   • When the chain reaches a decision a specific person made (a design choice, an omitted check, a misread requirement) and that reasoning can't be confirmed — the author is unavailable, or no conversation history/decision log was kept — treat that link as an unconfirmed hypothesis, not a conclusion. Say so explicitly in the output rather than folding it into the chain as fact, and if the author is reachable, ask them to confirm or correct it before finalizing.
   • Exception — migration-origin defects: when the defect comes from porting or refactoring existing behavior, the root cause often lives in the input being migrated (the original source) rather than in an undocumented human decision. Here the chain can usually be traced with high confidence by diffing against the source, even with no author or conversation history available.
   • The chain isn't limited to code: when relevant, also check how the underlying story or epic was written (ambiguous acceptance criteria, an unhandled edge case never specified) as a candidate root cause, not just the code that implemented it.
5. Inspect why it wasn't caught earlier (outflow). Compare the actual detection stage to the earliest stage where it plausibly could have been caught. Run this as its own short whys-style drilldown, separate from step 4 — the missed-detection root cause is often a process/tooling gap (missing test, no lint rule, no reviewer checklist item), not the same cause as the defect itself.
6. Distill a learning-sharing item. Before proposing fixes, write a short, shareable summary of the misconception or gap uncovered in steps 4–5 (a PR/Jira comment, a Slack message, a one-slide recap) that lets a teammate who wasn't involved understand it in under a minute. A root cause that only lives in one person's head doesn't prevent the next occurrence — this is what actually spreads the learning.
7. Document countermeasures. Record containment already performed and propose any remaining immediate fixes. Distinguish completed actions, observed results, and proposals; containment need not prevent recurrence.
8. Design eradication measures. Go deeper than the countermeasure: what permanent change (process, tooling, automated check, documentation, training) makes this entire class of defect structurally unable to recur — including recurring undetected until a late stage? Prefer micro-guardrails: small, automated, reversible checks (a one-line lint rule, a single added test, a doc snippet linked from the PR template) over large refactors. A tiny guardrail that ships beats a sweeping fix that never lands or introduces its own defects. Don't label something eradication if it only addresses this one instance.
9. Verify prevention and monitor recurrence separately. Demonstrate that the guardrail detects or prevents the original defect with a reproducer or regression check; record the result and the scenarios covered. Keep untested measures marked as proposed or unverified. Record recurrence monitoring with its time window and workload or opportunities for recurrence; an uneventful period is an observation, not proof of eradication. For ongoing tracking, define an owner and review point.

Prioritizing eradication measures (optional, for recurring/team use)

When there are several candidate eradication measures and they need to be triaged — e.g. in a recurring team slot rather than fixed on the spot — score each candidate and favor the ones that are automated, low-risk, and scoped to this defect's area rather than one that touches unrelated services:

Criterion	What to check
Impact	Would it have prevented this defect, and similar ones, from recurring?
Complexity / risk	Could it introduce new bugs or destabilize unrelated code?
Effort	How much work to implement per developer?
Time to verify	Can it be verified automatically (fast) or does it need manual checking (slow)?

Pick a small number of top-scoring, low-risk items per cycle rather than attempting all candidates at once — batching too much at once causes the fire-fighting/large-refactor instability this method is meant to avoid.

Team cadence (optional, reference practice)

For teams running this continuously rather than as a one-off, this adaptation uses:

• One bug-fix analysis per day, owned by the tech lead: review the diff, log the root cause, check the codebase for similar latent defects.
• A short daily sync (10–15 min, "Bug Fix Analysis Coffee") where the team proposes countermeasures together — new lint rule, an edge-case fixture, a small fix-driven refactor. Frame this as a help chain, not a command chain: the tone is "let's look at where the process didn't go as expected and figure out a countermeasure together," not "stop doing X, do Y instead." The point is coaching people toward catching their own gaps, not assigning blame.
• React within 24 hours of the defect surfacing, so the analysis happens while context is still fresh.

Suggest this cadence only if the user is setting up an ongoing team practice, not for a single defect write-up.

Reducing A-defects: "Right the First Time" (optional technique)

To specifically drive down Stage-A defects (caught while coding), use a constraint: a developer gets one manual test/refresh attempt per feature; if it fails on that first try, it counts as an A-defect. This pushes developers toward upfront design and TDD (so correctness is checked via fast terminal test runs instead of repeated manual clicking), and teams that nail a feature on the first attempt can be recognized publicly (e.g. a Slack bot shout-out). Offer this only as a targeted technique for A-defects, not as a general eradication measure for other stages.

Gotchas

• An AI agent can reliably trace where a defect entered the code, but not why a person chose to write it that way. Without the author available to confirm or a preserved decision log/conversation history to check against, that part of the chain is a hypothesis, however confidently it reads — never present it as a settled root cause. This is a hard limit, not a prompting problem to work around.
• If step 4 or step 5 surfaces a gap where "why" can't be reconstructed because no one wrote down the reasoning at the time, that's itself a finding: a missing decision log is a valid eradication candidate (require a short written rationale for that class of decision going forward), separate from whatever code fix addresses the immediate defect.
• Countermeasure and eradication are not interchangeable: a countermeasure fixes this occurrence; eradication prevents the class of defect from happening again. Keep them in separate sections and don't let a countermeasure masquerade as eradication.
• The 5 Whys chain must start from the defect description written in step 1, not from a vaguer symptom the user mentioned in passing.
• "Why did it happen" (step 4) and "why wasn't it caught" (step 5) are separate drilldowns — don't merge them into one chain.
• If the user is unsure of the detection stage or the defect description, ask a direct question rather than picking the most likely option yourself.
• Eradication doesn't mean "big refactor." Prefer the smallest automated check that closes the gap; oversized fixes are more likely to get deprioritized or introduce their own defects.
• Classify by stage, not severity — resist the urge to reintroduce a Low/Medium/High axis; it optimizes for the wrong question here.
• Write the final report in the same language the user used to describe the defect.
• Watch for two failure modes that both masquerade as rigor: "magical thinking" — assuming there must be one single root cause that explains everything, so the chain stops the moment a plausible answer appears — and "diffuse causation" — treating everything as connected to everything, which can be used to justify almost any proposed action. Both skip the actual verification step; a real whys chain stays narrow and keeps checking each link against evidence.

Output template

For a single defect analysis, use the structured template in _template.md. It defines the full document structure — metadata table, problem statement, causal chain, root-cause analysis, detection-failure causes, countermeasure, and eradication — with inline guidance comments in each section.

Include only causes supported by evidence. Mark unconfirmed explanations as hypotheses and missing information as unknown; omit inapplicable subsections rather than inventing a misconception or detection failure to fill them.

Fill the "Causal Chain" and "Root Cause of Occurrence" sections with the defect description, the recurrence check, the full 5-whys chain, and the "why not caught earlier" analysis (the latter goes in "Detection Failure Causes"). Keep "Countermeasure" and "Eradication" strictly separate.

If the user also wants the learning-sharing item or the prioritization scoring captured in the document, add optional ## Learning to share and ## Prioritization sections — don't add them by default, only when asked or when clearly working at team/recurring level.

If the user wants this saved as a file rather than shown inline, write it as a Markdown (.md) file.

---

Benchmark

Scenario: .benchmarks/scenarios/dantotsu-001-escape-stage.md · Run: 2026-08-31 · Log: .benchmarks/runs/2026-08-31/dantotsu-001-escape-stage.json

Model	Without	With	Delta
claude-opus-4-8	67%	100%	+33%
claude-sonnet-4-6	83%	100%	+17%
claude-haiku-4-5	83%	100%	+17%

PASS (run 2026-08-31). Small uniform gains; baselines partially apply the stage-classification-first rule unaided. Gate per .agents/skills/skill-optimizer/rules/release-gates.md.