Architecture Improve

Architecture Improve

Deep-research an architecture-map (map.js) for what to change, then paint each idea back onto the map as a proposed node carrying a structured proposal. The sibling of architecture-cleanup: map = WHAT exists → cleanup = what to REMOVE → improve = what to CHANGE.

Core principle — proposals-only. improve surfaces optimisation ideas and draws them on the map. It NEVER edits source, opens PRs, or applies a change (ADR-012: only cleanup gets an execution layer; improve's changes are judgment-heavy refactors, not mechanical removals).

When to use

• "Optimise the architecture", "improve the pipeline", "where can this be better".
• After mapping (and ideally cleaning) a repo, to plan structural/flow improvements.
• Not for line-level perf, micro-optimisation, or product/feature redesign (D4 boundary).
• Not for finding dead code to delete — that's architecture-cleanup.
• Recommended order: cleanup → improve (don't optimise code you're about to delete).

Input — map.js (ADR-010)

The input is /architecture-map/map.js (window.MAP_DATA). If it doesn't exist, build it first with the architecture-map skill, then run improve on the result. If a fresh architecture-cleanup overlay exists, improve reads it (see Cross-skill, ADR-014).

The two lenses (D4)

Every proposal is tagged with exactly one lens:

• 🏗️ structure — coupling, god-nodes (high fan-in + fan-out), duplicate subsystems, layering

violations, missing seams.

• 🔀 pipeline — redundant hops, serial steps that could run in parallel, idempotency/retry

gaps, data stored as expiring temp URLs instead of re-hosted, missing back-pressure.

Step 1 — deep research (fan-out, C3 gate)

1. Ensure the map exists & is fresh. No map.js → build via architecture-map. A stale map

gives stale proposals, so re-map if the repo moved.

1. Cheap seed signals (deterministic). Reuse cleanup's topology helper to focus the research —

it gives per-node degree (god-node = high inbound+outbound), duplicateGroups (dup tech), and blast-radius: ``bash node ../architecture-cleanup/analyze-map.mjs /architecture-map/map.js > /tmp/seed.json ``

1. Cost gate (C3) — warn on scale BEFORE firing. Reader count = number of subsystems on the

map. If it is > 8, tell the user the count + a rough token estimate and wait for a go. At/under 8, proceed.

1. Fan out, one reader per subsystem. Reuse architecture-audit's Map-phase pattern

(scout + parallel readers via the Workflow tool / subagents). Each reader carries BOTH lenses in its brief and is pre-seeded with seed.json hints for its subsystem (high-degree nodes, dup groups). One reader per subsystem keeps the agent count = subsystem count. Each reader returns candidate proposals: {problem, change, tradeoff, effort, impact, lens, affectedNodes[]}.

Step 2 — synthesize & prioritise (Q1)

1. Dedup & merge candidate proposals across subsystems (one synthesis pass).
2. Light verify the big ones. For high-impact proposals, sanity-check the claim against the

code before committing it to the map (honesty principle — no plausible-but-wrong proposals). This is a check, not a second full fan-out.

1. Band each proposal from its effort (S/M/L) × impact (low/med/high) — **discrete bands,

never a numeric score** (we have no telemetry; a number would be false precision):

| Band | Condition | |------|-----------| | ⚡ quick win | impact high · effort S | | 🎯 big bet | impact high · effort M/L | | 🧹 fill-in | everything else | | ⛔ skip | impact low · effort L (surfaced, recommended against) |

Step 3 — write proposals onto the map

Each proposal becomes a proposed node (the change drawn) + edges to the shipped nodes it affects. The structured proposal:{} object lives on the proposed node, never on a shipped node — a field on a shipped node would be dropped by merge-map.mjs on the next audit, whereas proposed nodes/edges survive re-audit (ADR-013).

1. Git-snapshot the map FIRST (ADR-011). Make sure map.js is committed (or stash-clean) so

backout is one git restore.

1. Build proposals.json — an array of `{node:{id,label,tech?,engine?,subsystem?},

proposal:{problem,change,tradeoff,effort,impact,lens}, edges:[{from,to,data}]}. See helper --selftest for the exact shape. id`s must be NEW (a proposed id may not clobber a shipped node).

1. Apply (additive, idempotent):

``bash node apply-proposals.mjs /architecture-map/map.js /tmp/proposals.json > /tmp/map.js \ && mv /tmp/map.js /architecture-map/map.js ``

1. Refresh the viewer if it predates the proposal panel:

cp ../architecture-map/assets/index.html /architecture-map/.

Step 4 — report (Q6)

improve has no fixed taxonomy (optimisation is open-ended) — but a fixed proposal shape and a fixed ordering. Hand the user:

• A header line: N proposals — X quick wins, Y big bets.
• One plain-language card per proposal (format:

../architecture-cleanup/references/finding-card-and-issues.md — What it is / Why it is an improvement / What you gain / Risk, technical detail folded). Grouped by band (⚡ quick wins → 🎯 big bets → 🧹 fill-ins → ⛔ skip). The raw problem/change/tradeoff + effort/impact + affected nodes + lens live in the folded Evidence block.

• The open command: open /architecture-map/index.html. A 💡 Proposals (N) toggle

(on by default) rings the proposed nodes amber; clicking one shows the full proposal block.

Step 5 — PRD-ready tracker issues (on approval)

When the user approves proposals (per proposal or per band), convert them to issues in the project's tracker (Linear, GitHub Issues, Jira — via its workflow skill if you have one). Structure, sub-issue PRD template (Background/Solution/Acceptance criteria/Risk/Evidence), estimate/label/priority mapping: all in ../architecture-cleanup/references/finding-card-and-issues.md. Parent Improve: () + one sub-issue per approved proposal. Draft the whole batch, show the user titles + estimates, ONE go creates them. Unapproved proposals stay on the map only. This does NOT change ADR-012: improve still never executes — the issues are the handoff to whoever builds.

Cross-skill with cleanup (ADR-014)

If a removable overlay is present, improve reads it and routes around it:

• Exclude removable-flagged nodes from the candidate set — don't optimise code already slated

for deletion. Report: "N nodes skipped (flagged removable by cleanup)".

• Routing around or replacing a removable node is fine (additive).
• If a proposal would build on a removable node, surface the conflict explicitly — never build

silently on something being deleted.

Cost (C3)

Step 1's seed pass is static/cheap. The fan-out warns on scale (reader count > 8) before firing. There is no removal/execution cost — improve only proposes.

Helpers

• apply-proposals.mjs — additive, idempotent write-back of proposed

nodes/edges + proposal:{} objects (ADR-011/013). Validates bands + edge endpoints; throws rather than write garbage. --selftest to verify.

• Reuses ../architecture-cleanup/analyze-map.mjs for the deterministic seed signals (degree,

duplicate-tech, blast-radius). No second analysis helper.

Red flags — STOP

• About to edit source / open a PR / apply a change → don't. improve is proposals-only (C2/ADR-012).
• About to put proposal on a shipped node → wrong; it must live on a proposed node (ADR-013).
• About to assign a numeric priority score → wrong; bands only (Q1).
• About to propose a line-level perf tweak or a feature redesign → out of scope (D4).
• About to optimise a node cleanup flagged removable → stop; exclude or surface the conflict (ADR-014).
• About to fan out > 8 readers without warning the user → stop, warn first (C3).
• About to create tracker issues without the batch-go → stop (Step 5).
• Report card leads with node-ids/paths instead of plain language → wrong; detail goes in the folded Evidence block.

Source & license

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

• Author: MartinPLarsen
• Source: MartinPLarsen/claude-architecture-skills
• License: MIT

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