assess-architecture git:20261108.7e14cbbB

Immutable. This exact content never changes and is served at /api/v1/blob/15e78d25fdaa60ce.

---
description: Assesses the current repository's architecture area by area for evidence-backed systemic refactorings (duplicated knowledge, misplaced ownership, reinvented abstractions, crossed boundaries) and saves the findings the user picks as refactoring ideas, for a later planned change to pull in. Invoked when the user wants to assess the architecture, find refactoring opportunities across the codebase, or runs /aido:assess-architecture.
disable-model-invocation: false
---

# Assess the Architecture

Review the repository's design area by area, apart from any feature. Park the findings the user picks
as refactoring opportunities. `/aido:1-plan` offers them when a planned change can include them, so
each refactoring is made as part of a working feature.

This skill reads the repository and never edits it. It writes only the opportunity files the user
explicitly picked, which live outside the repository.

Load `${CLAUDE_PLUGIN_ROOT}/guidelines/language.md` and follow it in everything you write for a person.

## Step 0: Load Context

- find `<repo-name>` and the index directory, as **Index Location and Shape** in
  `${CLAUDE_PLUGIN_ROOT}/guidelines/architecture-index.md` defines them
- load:
  - `${CLAUDE_PLUGIN_ROOT}/guidelines/systemic-refactoring.md`: what to look for, the evidence rule
    and how to park an opportunity
  - `${CLAUDE_PLUGIN_ROOT}/guidelines/code-standards.md`: its "Architecture" and "Code Quality" hold
    the rules each finding is judged by
  - `${CLAUDE_PLUGIN_ROOT}/guidelines/project-conventions.md`. Then gather the host repository's
    conventions as it describes
- run `git fetch origin`
- **no index** → `AskUserQuestion`: "This repository has no map of its architecture, and the assessment needs one. Should I build it first?" — options **Run /aido:map-architecture first** / **Cancel**. On the first, run that skill, then
  continue here
- **index stale** (see **Staleness** under **Index Location and Shape**) →
  `AskUserQuestion`: "The architecture map is `<n>` commits old. Should I update it first?" — options **Update it first
  (Recommended)** / **Assess with it as is**

## Step 1: Choose the Scope

Read `architecture/README.md` and show its areas. Then `AskUserQuestion`: "Which areas should I
assess?" — options **All areas** / **Specific areas** (the user names them).

## Step 2: Assess Each Area — `fable` subagents

Launch one `Agent` per area with `model: "fable"`, in parallel. Brief each with
"The Shared Brief" in `${CLAUDE_PLUGIN_ROOT}/guidelines/subagents.md`, and:

- the area's two file paths, `<area-slug>.md` and `<area-slug>.extra.md`. The second holds the
  infrastructure, misfits and observations this assessment needs. Add the `README.md` path and the
  repository root
- to look across the area's boundary by searching the other areas' files for this area's rules and
  terms, as **Reading the Index** in `${CLAUDE_PLUGIN_ROOT}/guidelines/architecture-index.md`
  describes. Not by reading them whole
- "The Design-Check Brief" in `${CLAUDE_PLUGIN_ROOT}/guidelines/subagents.md`
- to apply it inside the area **and** across its boundary, such as the same rule enforced in this area
  and another
- to treat the index as a map only, and read the code before claiming anything
- to group related findings in the area into one candidate, so there are few
- to return only this, per candidate:

  ```markdown
  ### <title, plain language, no prefix>
  - **Category:** duplicated knowledge | misplaced ownership | reinvented abstraction | crossed boundary
  - **Size:** S | M | L
  - every field under **What every finding states** in `systemic-refactoring.md`
  ```

  then one line listing the hypotheses it checked and rejected, so the user sees what was ruled out.

If `fable` is unavailable, act as "When the Model Is Unavailable" in
`${CLAUDE_PLUGIN_ROOT}/guidelines/subagents.md` describes.

## Step 3: Confirm and Present the Findings

Confirm each finding before showing it, as **Evidence before action** in `systemic-refactoring.md`
describes. Drop a finding the code doesn't support. It isn't offered for parking.

Number every confirmed candidate across all areas, and show them grouped by area: one line per
candidate, with its size, as **Showing a finding** in `systemic-refactoring.md` describes. Close with
the dropped findings, each with its reason and outside the numbering. Then the rejected hypotheses,
and which areas had no findings.

If nothing was found or confirmed, say so, list any dropped findings, and stop. That is a valid
result.

## Step 4: Park the Opportunities

Ask which of the numbered candidates from Step 3 to park: "Which of these should I save for later?",
as "Asking Questions" in `${CLAUDE_PLUGIN_ROOT}/guidelines/language.md` describes for picking from a
list.

Park each picked candidate as **Parking an opportunity** in `systemic-refactoring.md` describes. Its
**Category** names the design smell. When a file with the same evidence already exists, show it and
`AskUserQuestion`: "`<file>` looks like the same refactoring idea. What should I do?" — options
**Skip** / **Replace it**.

## Step 5: Report

List each refactoring idea saved, with its file path. List each skipped candidate and each dropped
finding, with the reason, and any step that fell back from `fable` to the session's model. Then end
as "Ending a Skill" in `${CLAUDE_PLUGIN_ROOT}/guidelines/language.md` describes. When nothing was
found, end the same way.

## STOP — Skill Complete

Do NOT refactor anything or edit the repository.