muda-audit 0.1.0

A Lean waste audit for your codebase. Walk the gemba, see the seven wastes, improve.

muda 無駄

A Lean waste audit for your codebase. Walk the gemba, see the seven wastes, improve.

---

Toyota taught the manufacturing world to see seven kinds of waste — muda — on the shopfloor: transport, inventory, motion, waiting, overproduction, overprocessing, defects. After six years of walking real factory floors as a Lean consultant, I kept seeing the same seven patterns in every codebase I touched. Nobody had named them there.

muda is a CLI that performs a gemba walk through a repository: it goes to the real place, observes without judgment, maps every observation to one of the seven wastes, and then does what Lean always does next — a Pareto cut to show you the vital few wastes worth fixing first.

My consulting principle is "Weglassen vor Automatisieren" — eliminate before you automate. This tool is that principle, executable.

╭─────────────────────────────────────────────────╮
│ muda 無駄 · gemba walk of ./demo-shop           │
│ 6 files observed · 11 findings · waste score 20 │
╰─────────────────────────────────────────────────╯
The seven wastes
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Waste          ┃ Findings ┃ Score ┃ Share ┃ Pareto                     ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Defects        │        3 │     8 │   40% │ ██████████████████ ◀ focus │
│ Inventory      │        3 │     5 │   25% │ ███████████ ◀ focus        │
│ Motion         │        2 │     2 │   10% │ ████ ◀ focus               │
│ Overprocessing │        1 │     2 │   10% │ ████ ◀ focus               │
│ Waiting        │        1 │     2 │   10% │ ████                       │
│ Overproduction │        1 │     1 │    5% │ ██                         │
└────────────────┴──────────┴───────┴───────┴────────────────────────────┘
Pareto: the ◀ focus wastes account for ~80% of the score. Start there.

┃ fix now    ┃ defects   ┃ Debugger left in code      ┃ src/app.py:15    ┃
┃ fix now    ┃ defects   ┃ Possible hardcoded secret  ┃ src/app.py:5     ┃
┃ should fix ┃ inventory ┃ Dependency never imported  ┃ requirements.txt ┃
┃ should fix ┃ waiting   ┃ Stale TODO (waiting 260d)  ┃ src/app.py:4     ┃

╭──────────────── Kaizen — built-in heuristics ────────────────╮
│ 1. Defects: Fix severity-3 items today: remove debuggers,    │
│    rotate anything that looks like a committed secret …      │
│ 2. Inventory: Delete what git already remembers …            │
╰──────────────────────────────────────────────────────────────╯

The mapping: shopfloor → codebase

The core idea of this project is a translation table. Each waste keeps its original manufacturing meaning and gets a concrete, checkable software equivalent:

Waste 無駄	On the shopfloor	In your codebase — what muda checks
Transport	Moving parts between stations without adding value	Pass-through modules that only shuttle imports/re-exports
Inventory	Stock on shelves binding capital and hiding problems	Dependencies declared but never imported; commented-out code blocks
Motion	Workers walking and reaching for badly placed tools	Oversized files, overlong functions, deeply nested paths
Waiting	Half-finished work queuing for the next station	TODO/FIXME/HACK comments — aged via git blame, the older the worse
Overproduction	Producing ahead of any real demand	Functions and classes defined but referenced nowhere
Overprocessing	Machining the same part twice at two stations	Byte-identical duplicate files
Defects	Scrap and rework escaping downstream	Leftover debuggers, bare except:, dynamic eval, hardcoded secrets

Run muda wastes to see this table in your terminal.

Quickstart

pipx install git+https://github.com/baris2828/muda-audit   # or: pip install .
muda walk .                          # audit the current repo
muda walk . --top 25                 # show more findings
muda walk . --report audit.md        # Markdown report for the PR / wiki
muda walk . --json audit.json        # machine-readable, for dashboards
muda walk . -x "*.ipynb" -x "docs/*" # exclude globs

Repo and package are named muda-audit; the command is simply muda.

Try it in 30 seconds

python examples/build_demo.py    # generates ./demo-shop — a tiny webshop full of deliberate waste
muda walk demo-shop              # watch the walk surface all seven wastes

The generated shop gets a git history dated ~8 months back, so git blame can age its markers into stale ones. The walk deliberately ignores .gitignore, so a repo-root muda walk . will flag the shop too — delete demo-shop/ when you are done playing.

The kaizen layer: an optional sensei

Seeing waste is step one; Lean is about the countermeasure. After each walk, a sensei turns the Pareto profile into prioritized kaizen advice. Two interchangeable advisors sit behind one interface (Strategy pattern):

• HeuristicSensei — curated guidance per waste, ships with the tool, works offline. Default.
• AISensei — sends an anonymized summary (scores + top findings, never your source files) to the Anthropic API for repo-specific advice.

pip install "muda-audit[ai]"          # the SDK is an optional extra, never a hard dependency
export ANTHROPIC_API_KEY=sk-ant-...
muda walk . --ai

Graceful degradation is a feature, not a fallback: no key, no SDK, no network, or a failed call — the audit still completes with heuristic advice and tells you why. The core tool has exactly two dependencies (typer, rich) and never requires the cloud.

Variable	Purpose	Default
ANTHROPIC_API_KEY	Enables the AI sensei with --ai	unset → heuristics
MUDA_MODEL	Override the model	claude-haiku-4-5-20251001 (current models)

CI quality gate: stop the line

In the Toyota Production System, any worker can pull the Andon cord and stop the line when they see a defect. --fail-on-score is that cord for your pipeline:

# .github/workflows/quality.yml
- name: Lean waste gate
  run: |
    pip install git+https://github.com/baris2828/muda-audit
    muda walk . --fail-on-score 25 --report muda-report.md

The budget is yours to choose: start where your codebase is today, then ratchet it down — that is kaizen, continuous improvement, encoded in one CI number.

muda audits muda

This repository holds itself to the strictest setting. CI runs muda walk . --fail-on-score 0 on every push: any waste in this codebase stops the line. Building that meant eating the classic scanner problem of self-reference (a waste detector finds its own detection patterns) — solved by counting markers only inside real code comments and camouflaging fixture strings in tests, the same techniques security scanners use.

Architecture

flowchart LR
    A[walker.py<br/>the gemba walk] -->|FileInfo| B{wastes/ registry}
    B --> C1[transport]
    B --> C2[inventory]
    B --> C3[motion]
    B --> C4[waiting]
    B --> C5[overproduction]
    B --> C6[overprocessing]
    B --> C7[defects]
    C1 & C2 & C3 & C4 & C5 & C6 & C7 -->|Findings| D[scoring.py<br/>waste score + Pareto]
    D --> E[sensei.py<br/>Heuristic / AI advice]
    D --> F[report.py]
    E --> F
    F --> G1[terminal · Rich]
    F --> G2[markdown]
    F --> G3[json]

Design decisions, in the order I made them:

1. One walk, many observers. The repository is traversed exactly once; checks receive immutable FileInfo records and re-read no text content. The only exceptions are deliberate: the duplicate check hashes file bytes, the waiting check consults git blame.
2. A registry, not a framework. Each waste is one module implementing one Protocol. An eighth waste is one new file plus one import line — walker, scorer and reporters stay untouched (open/closed principle).
3. Strategy for the sensei. Heuristic and AI advisors are interchangeable behind get_advice(); the AI path degrades to the heuristic on any failure, so the audit never depends on the network.
4. Render three times, analyze once. Terminal, Markdown and JSON views consume the same findings and scores. Rendering never re-runs analysis.
5. stdlib-first. Parsing uses ast, tomllib, hashlib, subprocess from the standard library. Two runtime dependencies, both for presentation.

Honest limitations

muda is a gemba walk, not a court ruling. The checks are deliberately conservative heuristics: unused-dependency detection knows common alias mappings (scikit-learn → sklearn) but not every plugin system; dead-code detection counts any textual mention as demand, so it under-reports rather than over-reports; duplicate detection is byte-exact only. Findings are severity-graded conversation starters for a kaizen session — verify before you delete. Currently strongest on Python, with basic JS/TS support. The checks were calibrated by field-testing against 14 real-world repositories.

Roadmap

Near-term: near-duplicate detection (normalized-AST hashing), a --diff mode that audits only changed files in a PR, per-repo thresholds via muda.toml, and an eighth check for the "unused talent" waste some Lean schools add — undocumented public APIs.

About

Built by Baris Aydin — Lean Management consultant (M.Eng.) turned Data Scientist, six years of process consulting across aerospace, steel, automotive and logistics. This tool exists because the seven wastes turned out to be a portable lens: they work on a shopfloor in Bremen and in a src/ directory alike.

Weglassen vor Automatisieren — eliminate before you automate.

LinkedIn · GitHub

License

MIT