coupling-map

Coupling Map

Answers one operational question: which files should be refactored first to reduce systemic risk. A file qualifies when both conditions hold — it does too much, and enough of the system depends on it that breaking it breaks several other parts.

The output is a standalone HTML report. It is diagnostic, not a gate: it fails no build and blocks no commit.

References, loaded on demand, all of which travel with this skill: references/config-schema.md (every field of arch.config.json), references/report-contract.md (the shape of architecture.json), references/calibrating-cuts.md (deriving thresholds for a new codebase), references/rejected-metrics.md (read before proposing any metric or axis).

The full design argument lives in docs/Skill_Coupling_Map.md of the sdd-skills repository, which is not part of an installed copy. Everything needed to run is in the folder you are reading.

The point of the split is cost. The model inspects the tree exactly once, to write a config of about thirty lines. From then on it reads a single JSON file. On the codebase this was built against that is one file instead of 959, and the numbers are identical either way because the script computed them, not the model.

INPUT

Nothing required. Optionally a path to scope the run, --config / --out to override locations, and --open to launch the finished report in the default browser.

OUTPUT

• architecture-report/index.html — the report, opened straight from disk. The script prints it as an absolute file:// URL, which most terminals turn into a link and which pastes into a browser as-is. Hand that link to the reader; a relative path leaves them working out where the file went.
• architecture-report/architecture.json — the data, and the only file this skill reads on later runs
• A short spoken summary: the queue, what moved since the previous run, and what needs a human

PHASE 1 — Preflight

Three checks, in this order. All three passing means skip straight to Phase 3.