git:20261023.7be5f6e to git:20261023.e4fc288

---

name: improve-architecture

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

and relevant design decisions. Use the project's context documents as they

exist, under the project's own names when it uses others: a root `CONTEXT.md`,

or, with a root `CONTEXT-MAP.md`, the `CONTEXT.md` of each affected context.

Create no documentation.

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 the revision being examined and unrelated local changes.

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

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. Present the recommendations

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.

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

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

out of Linear.

## 3. Draft the issues and obtain approval

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:** drafts approved. Otherwise keep them in the conversation.

## 4. Publish and hand over

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

parent first, then sub-issues attached to it, with native blocking relations.

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

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:** publication verified and each sub-issue ready for `implement`.