Cli Audit Hanoi

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.

1. 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.

1. 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.

1. 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.

1. 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.

1. Detect violations per law, using references/domains.md for the

canonical stack and anti-patterns of each domain.

1. 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.

1. 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.

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Destynova2
• Source: Destynova2/cli-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.