git:20260923.c68d399 to git:20260927.f916298

47 added, 146 removed. Audit A to A.

---

name: improve-architecture

- description: Find evidenced architecture improvements, present recommendations, and delegate each selected refactor through verified delivery and report updates.

+ description: Find evidenced architecture improvements and publish the approved ones as a Linear parent issue with one Task sub-issue per refactor, ready for implement.

disable-model-invocation: true

---

# Improve architecture

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

+ Identify architectural friction and turn the improvements the user approves into

+ Linear work. Prefer changes that hide implementation complexity behind a smaller,

+ clearer interface while preserving behavior. A review publishes one parent issue

+ and one Task sub-issue per refactor; `implement` delivers each sub-issue. The

+ request authorizes investigation and, after the user's approval, publication in

+ Linear. It does not authorize refactoring.

## 1. Scope the investigation

- 1. Read the request, project instructions, repository state, existing task record,

+ 1. Read the request, project instructions, repository state, existing Linear work,

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.

+ 3. Record the revision being examined and unrelated local changes.

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.

Use established project terms, including component, service, API, or module where

- appropriate. No external vocabulary skill is required. For each candidate, ask:

+ appropriate. For each candidate, ask:

- 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?

Names, file counts, and unfamiliar style alone are not defects. A speculative

benefit stays a hypothesis, not a promised performance or reliability gain.

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

- ## 2. Prepare the report and await selection

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

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

- Include these facts for each recommendation:

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

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

- 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 only these statuses in the French reader:

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

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

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

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

- ## 3. Dispatch the selected refactor

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

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

- Give each implementation worker this bounded brief:

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

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

- ```

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

+ ## 2. Present the recommendations

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

+ Present the candidates in the conversation as a numbered list, in the user's

+ language. For each one give a short title, affected paths, the observed friction

+ and its evidence, the proposed change (target interface, behavior to preserve,

+ exclusions), dependencies on other recommendations, and acceptance checks.

+ Add a Mermaid before/after diagram only where relationships need explanation.

+ Separate illustrative designs from observed implementation, and ask before

+ reopening an accepted design decision that conflicts with a recommendation.

- **Done:** the worker returns a reviewable checkpoint and evidence, or an explicit

- failure with preserved partial work. Dispatch alone is not implementation evidence.

+ Recommend where to start, then ask which recommendations to keep.

- ## 4. Verify, correct, and deliver

+ **Done:** the user has selected the recommendations to publish; the others stay

+ out of Linear.

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

+ ## 3. Draft the issues and obtain approval

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

+ 1. Draft the parent issue with the [review template](templates/review.md). It

+ carries no Type label: it groups the review's sub-issues and is delivered

+ through them.

+ 2. Draft one sub-issue per selected recommendation with the

+ [Task template](../triage/templates/task.md) and the Task label:

+ - **User story:** as a maintainer of the area, the change and the concrete

+ work it makes cheaper.

+ - **Context:** observed friction, evidence, affected paths, and revision.

+ - **Scope** and **Out of scope:** the target interface, the change, and its exclusions.

+ - **Acceptance criteria:** Given/When/Then scenarios on the caller-visible

+ behavior that stays the same and on the new interface.

+ - **Verification:** the passing behavioral baseline to preserve, and the

+ characterization tests to add first where that behavior is not covered.

+ 3. Express each dependency between recommendations as a blocking relation between

+ sub-issues.

+ 4. Present the drafts and obtain approval of their content and publication.

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

+ **Done:** drafts approved. Otherwise keep them in the conversation.

- ## 5. Report back and stop

+ ## 4. Publish and hand over

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

+ Publish with the [triage publication rules](../triage/SKILL.md#4-publish-and-hand-over):

+ parent first, then sub-issues attached to it, all in Backlog, with native blocking

+ relations. Verify content, labels, parent membership, status, and relations.

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

+ The parent is complete when all its sub-issues are Done; Linear closes it

+ automatically when the team enables Parent auto-close. Return the named links,

+ the recommended first sub-issue, and point to `implement` to deliver it.

- **Done:** the user can see what actually finished and what remains. Blocked work is

- an incomplete result, not successful completion of the run.

+ **Done:** publication verified and each sub-issue ready for `implement`.