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.

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

Workflow

Work through these steps in order. Don't skip ahead to root cause before the defect and stage are pinned down — the whole analysis is only as good as that starting point.

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.

1. 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.
2. 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.
3. Propose countermeasures. Short-term, containment-level fixes: patch the immediate occurrence, stop the bleeding (hotfix, rollback, manual workaround). These don't need to be elegant or prevent recurrence — they need to be fast.
4. 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.
5. Follow the eradication measure through to verified non-recurrence. This is "weak point management": flagging the weak point and proposing a fix isn't the end of the loop — the loop only closes once the guardrail is confirmed to actually catch the next occurrence (or enough time/cycles have passed without recurrence). If the user is tracking this over time, ask them to check back rather than treating step 8 as the finish line.

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:

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.

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

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.