cli-audit-hanoi

name

cli-audit-hanoi

description

Audit the ordering and layering of install/config/build steps using the Tower of Hanoi model: stable-and-expensive at the bottom, volatile-and-cheap on top, no step before its prerequisite, minimal redone work per change, and no responsibility displaced to a higher layer (what the code does not do resurfaces in Docker, kube.yml, or Ansible — often paid three times). Applies to Dockerfiles/Containerfiles (layer cache, image size), Ansible playbooks/roles (task order, handler restarts, idempotence), Kubernetes manifests (apply order, CRD/RBAC/ConfigMap sequencing), Rust workspaces and build systems (crate layering, incremental compile blast radius), CI job ordering, long documents (reader-cache ordering), and cross-layer stacks (code -> image -> orchestrator -> config management). Use when the user says 'hanoi', 'Tours de Hanoï', 'ordre d'installation', 'ordre des tâches', 'layer order', 'layer caching', 'Dockerfile cache', 'ça rebuild tout', 'build lent', 'image trop grosse', 'restart storm', 'apply order', 'sync waves', 'tout recompile', 'incremental build', 'reorder steps', 'ordering audit', 'blast radius', 'multi techno', 'wait-for-it', 'initContainer hack', 'entrypoint sed', 'preStop sleep', 'la même logique dans docker et ansible', 'displaced responsibility'. Do not use for call-graph cycles and god functions (cli-audit-tangle), full CI pipeline redesign (cli-forge-pipeline), or benchmarking claimed gains (cli-forge-perf).

Hanoi Audit

Audit the order of operations, not the operations themselves. The same steps, intelligently stacked, produce something concise, clean, and fast; badly stacked, they produce rebuild storms, restart loops, and bloat.

Model: a Tower of Hanoi. Each step is a disk. Disk size = stability × redo cost. Touching a disk forces every disk above it to be redone. And in a multi-techno stack, the towers themselves stack: code → build → image → orchestrator → config management. A move skipped in a lower tower reappears in every tower above it.

Read ../gotchas.md before producing output — the conservation law applies doubly here: a reorder is only justified by measured rework, never by aesthetics.

The Three Laws

1. Big disk first (stability ordering). Order steps by change frequency and redo cost: stable and expensive at the bottom, volatile and cheap on top. Every inversion — a frequently-edited step sitting below a costly stable one — taxes each edit with the full stack above.
2. No move before its prerequisite (topological legality). A step never executes before what it depends on. Crashloop-until-ready and "run it twice" are retry-based ordering: a Law 2 violation with a costume on.
3. Count the moves (economy). Hanoi has a known minimum (2^n - 1). Code has one too: one change should redo only itself and what truly depends on it. Every extra restart, cache invalidation, re-download, or recompile is a wasted move.
4. Conservation of responsibility (multi-techno displacement). A capability the code does not provide does not disappear — it is compensated above, per tool and per environment, with weaker guarantees: shell instead of types, retries instead of contracts. No config reload in the app → checksum rollouts in kube and restart handlers in Ansible. No dependency retry in the app → wait-for-it in the entrypoint, an initContainer, and an Ansible until loop: the same missing move, paid three times.

Workflow

1. Inventory ordering-sensitive artifacts under the target path: Dockerfile/Containerfile, compose files, Kubernetes manifests (kustomize/Helm), Ansible playbooks and roles, CI YAML, build definitions (Cargo workspace, Makefile, package.json scripts), and long-lived documents. List what was found and what was skipped.
2. Build each stack. For each artifact, list steps in execution order. Annotate each step with:
   • change frequency — measured, not guessed: git log --since=6.months --name-only for file-level heat, git log -L for line ranges inside a Dockerfile or playbook;
   • redo cost — duration, download size, restart impact, image weight.
3. Detect violations per law, using references/domains.md for the canonical stack and anti-patterns of each domain.
4. Trace displaced responsibilities (multi-techno). For every compensation found in Docker/kube/Ansible — entrypoint sed, wait-for-it, initContainer sleep, preStop sleep, probes that grep logs, until loops around app start — identify the missing capability in the layer below using references/displacement.md. Count how many layers compensate for the same gap: two or more is a confirmed finding. Propose the fix at the source, or, when the source is out of reach (vendor binary, frozen legacy), consolidation into exactly one layer.
5. Measure blast radius. For the 2-3 most frequently changed inputs, count what gets redone today versus after the proposed reorder. This number is the finding; without it, there is no finding.
6. Propose the reordered stack: before/after stack diagram, patch sketch, expected win (build time, cache-hit rate, image size, restart count, first-apply success). Mark semantic risks explicitly — some orders encode real constraints; a reorder must be behavior-preserving or flagged NEEDS-REVIEW. A non-trivial reorder is a hypothesis until measured: shape it as an optimization card (../shared/optimization-card.md) — evidence, invariants, validation method, risk, owner.

Scoring

Score each artifact 0-10 per law:

Law	What drags the score down
Stability	inversions, weighted by change frequency × redo cost above them
Legality	prerequisite violations, races, retry-based ordering
Economy	wasted moves per typical change: restarts, invalidations, re-downloads, recompiles
Displacement (repo-level)	responsibilities compensated above their natural layer, weighted by how many layers pay for the same gap

Findings carry tier and confidence per ../shared/triage.md so cli-cycle can aggregate them without re-parsing prose.

Report shape — findings first:

## Verdict
[one line per artifact: score triple + the single worst inversion]

## Inversions (ranked by frequency × redo cost)
| # | Artifact | Step out of place | Law | Blast radius today | After reorder |

## Reordered stacks
[before/after diagram + patch sketch per artifact worth fixing]

## Displaced responsibilities
| Missing capability | Natural layer | Compensations found (layer: file) | Fix at source / consolidation |

## Points à vérifier
[semantic risks, unmeasured costs, NEEDS-REVIEW]

Rank fixes by gain ÷ effort. If the blast radius barely moves, say so and recommend leaving the file alone — churn is a cost, not a deliverable.

The Signature Inversion

The most common finding across all domains is the same disk misplaced: a small volatile piece at the bottom of the tower.

• Docker: COPY . . before dependency install.
• Rust: a daily-edited utils crate every other crate depends on.
• Ansible: an inline restart after each config file instead of one notified handler.
• Kubernetes: a ConfigMap applied after the workload that mounts it.
• Text: the conclusion the reader needs, buried on page four.
• Multi-techno: the same wait-for-db in entrypoint.sh, an initContainer, and an Ansible until loop — one missing retry in code, paid three times.

Name it when you see it — the pattern transfers across domains, and the fix is always the same: move the volatile piece up, or split it so the stable part can sink.

Read References On Demand

• references/domains.md — canonical stacks, anti-patterns, and quick checks per domain: container images, Ansible, Kubernetes, Rust/build systems, CI, text.
• references/displacement.md — the cross-layer catalog: missing capability in code → compensations you will find in Docker, kube.yml, and Ansible → fix at source, plus what is legitimate platform work and must not be flagged.

Relationship With Other cli-* Skills

Situation	Better handoff
Call-graph cycles, god functions, dead code	cli-audit-tangle
Full CI/CD pipeline redesign	cli-forge-pipeline
Benchmarking the claimed speed-up	cli-forge-perf
Migrating the deployment itself	cli-forge-oci-rootless, cli-forge-infra
Ordering information in an outbound message	cli-forge-plume
Run under the full project review	cli-cycle — emit .claude/cli-audit-hanoi.json per ../shared/result-schema.md for orchestrator aggregation

Recommend, do not auto-run.

Guardrails

• Measured rework is the only force that justifies a reorder. No "cleaner", no "best practice", no reordering files the user did not put in scope.
• Never propose a reorder that changes behavior silently: config written before its package exists, tasks whose order encodes a state timeline, K8s resources with real readiness dependencies. Verify or flag.
• Respect existing conventions (file names, YAML style, task naming) — this audit moves steps, it does not restyle them.
• If git history is unavailable, say the frequency column is estimated and lower confidence accordingly.