improve-architecture · diff
git:20260831.a1f56dc to git:20260923.c68d399
159 added, 95 removed. Audit A to A.
---
name: improve-architecture
- description: >-
- Scan a codebase for deepening opportunities, present them on a live canvas,
- then delegate each approved refactor to a bounded sub-agent while the canvas
- tracks progress.
+ description: Find evidenced architecture improvements, present recommendations, and delegate each selected refactor through verified delivery and report updates.
disable-model-invocation: true
---
- # Improve Architecture
+ # Improve architecture
- Surface architectural friction, propose **deepening opportunities** — refactors
- that turn shallow modules into deep ones — and drive the approved ones to
- verified completion. The aim is testability and AI-navigability. The main
- thread never refactors: it scans, presents, dispatches, reviews, and keeps the
- canvas current.
+ Identify architectural friction and deliver only the recommendations the user
+ selects. Prefer changes that hide implementation complexity behind a smaller,
+ clearer interface while preserving behavior. The main agent owns scoping,
+ delegation, review, report updates, and the final response. Implementation workers
+ own their bounded code changes; they do not independently expand the project.
- ## Vocabulary
+ ## 1. Scope the investigation
- Invoke the `codebase-design` skill before scanning; it is required. It
- supplies the architecture vocabulary (**module**, **interface**, **depth**,
- **seam**, **adapter**, **leverage**, **locality**) and its principles (the
- deletion test, "the interface is the test surface", "one adapter =
- hypothetical seam, two = real"). Use these terms exactly in every candidate
- and every work order; do not drift into "component", "service", "API", or
- "boundary". If the skill is not installed, stop and tell the user to install
- it first.
+ 1. Read the request, project instructions, repository state, existing task record,
+ and relevant design decisions. Use the project's actual glossary and document
+ locations; do not require or create CONTEXT.md or an ADR directory by default.
+ 2. Follow the user's named pain point or subsystem. Without one, inspect recent
+ changes and callers to find a bounded area where change is costly. Expand only
+ when evidence identifies another affected boundary.
+ 3. Record unrelated local changes and the revision or snapshot being examined.
+ A request for an architecture review authorizes investigation, not refactoring.
+ 4. Delegate independent scan questions when useful and supported. Give each worker
+ a read-only scope, inputs, expected evidence, and stopping condition. No fixed
+ agent quota, duplicate whole-repository scans, or recursive delegation.
- ## 1. Explore
+ Use established project terms, including component, service, API, or module where
+ appropriate. No external vocabulary skill is required. For each candidate, ask:
- **Scope before you scan: YAGNI.** Deepening pays off where change is coming,
- so weight recently changed code:
+ - Which concrete change requires understanding or editing too many places?
+ - Does an abstraction hide complexity, or merely forward calls and expose details?
+ - Can removing or merging a layer improve clarity without losing useful behavior?
+ - Are tests coupled to internal details instead of the caller-visible contract?
+ - Which existing callers, checks, or incidents support the proposed improvement?
- - If the user named a direction (module, subsystem, pain point), take it.
- - Otherwise walk back a good stretch of `git log --oneline` to find hot
- spots — files and areas that keep coming up — and let those paths pull your
- attention first. Scattered changes with no hot spot: widen the net.
+ Names, file counts, and unfamiliar style alone are not defects. A speculative
+ benefit stays a hypothesis, not a promised performance or reliability gain.
- Read the domain glossary (`CONTEXT.md`) and any ADRs in `docs/adr/` touching
- the area; ADRs record decisions this skill does not re-litigate.
+ **Done:** each retained candidate has affected paths, observed friction, a scoped
+ proposal, a reason to prefer it over leaving the code alone, and acceptance checks.
+ If no candidate survives, report that result without manufacturing work.
- Spawn one sub-agent to walk the scoped area and report friction; explore
- organically rather than by rigid heuristics:
+ ## 2. Prepare the report and await selection
- - Where does understanding one concept require bouncing between many small
- modules?
- - Where are modules shallow?
- - Where were pure functions extracted just for testability while the real
- bugs hide in how they are called (no locality)?
- - Where do tightly-coupled modules leak across their seams?
- - Which parts are untested, or untestable through their current interface?
+ Use the technical branch of [canvas](../canvas/SKILL.md) and its
+ [Markdown contract](../canvas/technical.md). Keep one task-specific reader and
+ source report throughout the work. Do not change the reader's design or edit its
+ bundled example to conduct a real architecture review. If the reader cannot run,
+ preserve the Markdown and report the preview limitation; do not claim it opened.
- Apply the deletion test to every suspect. The scan is complete when each
- candidate carries: involved files, the friction observed, the deletion-test
- result, and how tests would improve.
+ Write in the user's chosen report language. Keep stable IDs such as ARCH-01,
+ short sidebar titles of at most four words, and full explanations in the sections.
+ The current reader uses French tracker headers and statuses; follow its documented
+ language limitations rather than silently using an incompatible schema.
- ## 2. Present candidates on a canvas
+ Include these facts for each recommendation:
- Invoke the `canvas` skill and render the review as a **living artifact** —
- one file, kept for the whole run, updated in place at every stage below.
+ | Fact | Required content |
+ | --- | --- |
+ | Identity | Stable ID, short title, affected paths, and relevant snapshot |
+ | Problem | Observed friction and supporting evidence |
+ | Proposed change | Target interface, behavior to preserve, and exclusions |
+ | Dependencies | Explicit prerequisite IDs and unresolved decisions |
+ | Acceptance | Focused baseline, regression checks, and required runtime evidence |
+ | Delivery | Agreed local result, commit, or PR boundary; mark unresolved choices |
+ | Tracking | Status and next action, blocker, or verified delivery evidence |
- For each candidate, a card with:
+ Use Mermaid before/after diagrams only where relationships need explanation.
+ Do not mandate cards, diagrams for every finding, or tutorial blocks. Separate
+ illustrative designs from observed implementation. Identify conflicting accepted
+ design decisions and ask before reopening them.
- - **Files**: files and modules involved.
- - **Problem**: why the current architecture causes friction.
- - **Solution**: plain-English description of what would change.
- - **Benefits**: in terms of locality and leverage, and how tests improve.
- - **Before / after diagram**: side by side, illustrating the deepening.
- - **Recommendation strength**: `Strong`, `Worth exploring`, or `Speculative`.
- - **Status badge**: every candidate starts at `Proposed`.
+ The main agent is the sole writer of report state. The Markdown is the reader's
+ content source; where a project tracker exists, follow that record's authority
+ and authorized update rules rather than creating a competing backlog.
- Use `CONTEXT.md` vocabulary for the domain: if it defines "Order", write
- "the Order intake module", not "the FooBarHandler". A candidate that
- contradicts an ADR appears only when the friction justifies reopening the
- decision, with a visible warning naming the ADR.
+ Use only these statuses in the French reader:
- End with a **Top recommendation** section: which candidate to tackle first
- and why. Then ask the user which candidates to run — one, several, or all.
- Do not start work without a pick.
+ | Status | Meaning |
+ | --- | --- |
+ | À lancer | Work has not started, including recommendations awaiting prerequisites or deferred by the user |
+ | En cours | Work has started; implementation, corrections, review, or agreed delivery remains |
+ | Terminé | Required checks, acceptance, and the agreed delivery boundary are satisfied |
- ## 3. Delegate each approved refactor
+ Blockage, deferral, failed verification, and pending publication are notes, not
+ extra statuses. Never mark a blocked or rejected recommendation completed.
+ Place prerequisites before dependents in the table and retain dependency IDs
+ after completion; the reader projects its supported hierarchy from those entries.
- For each approved candidate, write a **work order** and spawn a sub-agent to
- execute it. The work order is the sub-agent's whole world, so it carries:
+ Recommend the next useful item, then await selection unless the current request
+ already names it. A message such as "Exécute ARCH-01" selects that recommendation;
+ resolve it from the existing report without requiring the user to repeat context.
+ An `agent-action` fence may supply a short copyable instruction naming the ID and
+ scope. Copying it, navigating, or checking a personal checkbox launches nothing.
- - **Scope**: the exact files and modules it may touch, and the statement that
- everything else is out of bounds. Behavior-preserving refactor only: no
- features, no drive-by cleanups, no dependency changes.
- - **Target shape**: the deepened interface — what callers will see, what
- moves behind the seam.
- - **Completion criterion**: the refactor is done when the full test suite
- passes and every caller compiles against the new interface. If the area has
- no tests, the sub-agent writes characterization tests against the current
- behavior first and keeps them green through the refactor.
- - **Report format**: files changed, interface before/after, test results, and
- any discovery that changed the plan.
+ **Done:** the report is reviewable, the chosen IDs are explicit, and unselected
+ recommendations remain untouched. A request for one item does not select the rest.
- Independent candidates (disjoint files) may run as parallel sub-agents; any
- two candidates whose scopes overlap run sequentially. On dispatch, flip the
- candidate's canvas badge to `In progress`.
+ ## 3. Dispatch the selected refactor
- ## 4. Review, verify, update the canvas
+ Before dispatch, recheck the selected recommendation against current code, accepted
+ scope, dependencies, and available evidence. A completed prerequisite must also
+ be available in the worker's actual revision or worktree. Stale or missing evidence,
+ a dependency cycle, or an unresolved decision pauses the dependent assignment.
+ Do not silently implement prerequisites the user did not select.
- When a sub-agent reports back, the main thread reviews before anything is
- marked done:
+ Reuse an existing worker for a continuation when appropriate. Independent selected
+ items may run in parallel only with disjoint write ownership and safe shared
+ resource use. Sequence overlapping or dependent changes. Respect available tools,
+ concurrency limits, and user budgets. Workers do not create user-owned conversations.
- - Read the diff. Confirm the scope held and the interface matches the work
- order's target shape.
- - Re-run the test suite from the main thread; the sub-agent's claim is not
- the evidence.
- - Passed: flip the badge to `Verified` and add a short outcome line to the
- card (what the interface became, test delta). Failed or scope drifted: flip
- to `Blocked` with the reason, and either re-dispatch with a corrected work
- order or surface the decision to the user.
+ Give each implementation worker this bounded brief:
- Side effects happen as results crystallize:
+ ```text
+ Recommendation ID and objective:
+ Repository, branch/worktree, baseline, and existing task record:
+ Authoritative requirements, project instructions, and accepted decisions:
+ Prerequisites and evidence they are available:
+ Permitted files/areas, callers to check, exclusions, and unrelated local work:
+ Target interface and behaviors/public contracts to preserve:
+ Acceptance checks, passing baseline or characterization tests, runtime evidence:
+ Affected documentation and context changes:
+ Delivery boundary and explicitly authorized Git/external operations:
+ Return: scoped diff/checkpoint, changed paths, checks actually run and results,
+ remaining limitations, real commit/PR identifiers if produced, and next action.
- - A deepened module named after a concept missing from `CONTEXT.md`: add the
- term (create the file lazily).
- - The user rejects a candidate for a load-bearing reason: offer an ADR so
- future reviews do not re-suggest it. Skip ephemeral reasons ("not worth it
- right now").
+ Work only within this assignment. Do not edit the coordinator's report, start
+ other recommendations, recursively delegate, or publish outside the authorized
+ scope. Report a necessary scope expansion before proceeding with it.
+ ```
- The run is complete when every approved candidate reads `Verified` or
- `Blocked` on the canvas, and the closing message links the canvas with a
- one-line summary per candidate.
+ Apply the [implementation verification rules](../implement/SKILL.md) to the
+ assignment without assuming a manually invoked skill was automatically launched.
+ For refactoring, establish a passing behavioral baseline and preserve it. Add
+ characterization coverage first when the behavior is not adequately protected.
+ Run focused and project-required checks; do not demand the entire test suite for
+ every change or treat unrelated failures as new regressions.
+
+ Set En cours only after work actually starts, not merely when a launch is attempted.
+ If delegation is unavailable, keep the selected item pending and report the missing
+ capability. Do not quietly replace the agreed worker flow with main-agent coding.
+
+ **Done:** the worker returns a reviewable checkpoint and evidence, or an explicit
+ failure with preserved partial work. Dispatch alone is not implementation evidence.
+
+ ## 4. Verify, correct, and deliver
+
+ 1. Inspect the returned diff against the assignment, including callers, public
+ contracts, required documentation, and unrelated work. Treat the worker's summary
+ as a claim to check, not proof of completion.
+ 2. Use the [review-correction loop](../implement/references/review-loop.md) and the
+ available [code-review](../code-review/SKILL.md) procedure. The main agent verifies
+ findings; the implementation worker corrects confirmed in-scope problems.
+ Request targeted follow-up on the resulting checkpoint. Missing required review
+ remains pending, not an independent pass.
+ 3. Re-run relevant checks on the integrated result. Verify connected user-visible
+ behavior where applicable. Keep failed checks and blockers in the report notes
+ while the started recommendation remains En cours.
+ 4. Apply the [delivery boundary](../implement/references/delivery.md). A worker may
+ prepare an authorized scoped commit or PR, but the main agent verifies its actual
+ content and result. A local edit request does not authorize push, PR, merge,
+ deployment, or tracker writes. Ask only for missing material authorization.
+ 5. Update the report with actual outcomes, checks, and delivery links. Record any
+ authorized project-tracker update separately and verify it. Report a failed write
+ with the last confirmed state; do not claim synchronization.
+
+ Update relevant existing system documentation and domain terms within the approved
+ change. Do not create global project agreements or an ADR as an incidental side
+ effect. Propose a lasting decision record only when the decision warrants one.
+
+ **Done:** mark Terminé only when verification, acceptance, and agreed delivery hold.
+ A draft PR can be the agreed handoff, but does not establish merge or deployment.
+ If any required step remains, preserve En cours and name the pending action.
+
+ ## 5. Report back and stop
+
+ Return to the main conversation with the selected ID, outcome, affected paths,
+ checks, real delivery identifiers, and material limitations. Link the existing
+ report and state whether its update was verified. Keep completed, accepted,
+ committed, published, integrated, and deployed facts distinct.
+
+ After one selected recommendation, wait for the next instruction. A previously
+ approved batch may continue within its stated scope and dependency order; never
+ start unselected work automatically. On resume, reconcile the existing report,
+ code, delivery evidence, and project record before dispatching another worker.
+
+ **Done:** the user can see what actually finished and what remains. Blocked work is
+ an incomplete result, not successful completion of the run.