---
name: aide-analyze
description: >-
  Analyze the codebase for a spec.
  Detects complexity (LOW/MEDIUM/HIGH), maps affected files with
  file:line references, and creates an implementation plan with TDD.
  Use when: analyzing the codebase for an existing task,
  filling in 2-analysis.md and 3-solution.md, needing an overview of
  affected files and API impact.
  Do NOT use for: creating a new task (use aide-create),
  implementation (use aide-implement).
argument-hint: "[PROJ-XXXX or task number]"
effort: xhigh
---

Analyze the codebase for a spec.

**Input:** $ARGUMENTS (all arguments after the command)

## Smart detection

Parse `$ARGUMENTS`:

**The spec:** the first word is its number, its `TODO-<name>` folder, or an issue key its title began with
- Example: `/aide-analyze 55` or `/aide-analyze TODO-01`

**Error handling:** If the argument is missing or has an invalid format, show:

```text
Missing argument

Usage:
/aide-analyze 55               # the spec's number
/aide-analyze TODO-01           # or its folder

Examples:
/aide-analyze 55
```

---

## Workflow

The steps below are this skill's own, inside the queue's `analyze` step.
Mark each one in the log, so a reader can follow the run: when it
starts, write one line `--- Step N of X: <title> — started`, and when
it ends, one line `--- Step N of X: <title> — done`. A step that ends
the run early says `— stopped: <why>` in place of `— done`, and one that does not apply to this run `— skipped: <why>`.

Step 10, the merge into the default branch, is Aide's, after this
session: Aide writes its marks, and the analyze is finished only when it is
done.

### Step 1 of 10: Read the description

First write `--- Step 1 of 10: Read the description — started`, and when this step ends, `--- Step 1 of 10: Read the description — done`.


- Read `specs/XX-slug/1-description.md`
- Read `.aide/project.yaml` in the project root if it exists — the
  project manifest gives deployment, logging and dependency context
  the analysis should use (refresh it with `/aide-manifest`)
- **Read the project's wiki, when it has one, before anything else —
  in a later round too, before the earlier round's files.** The specs
  root is the folder that holds this spec's folder. If `wiki/` is beside
  it, run `aide-wiki status --specs-root <root> --project-dir .`, read
  `wiki/index.md`, then the pages that concern the change. A page whose
  state is `changed` or `unknown` is a map of where to look, and the
  code decides. When the answer is `"wiki":false`, or `aide-wiki` is not
  installed, skip this and write nothing about a wiki.
- Identify: What should change? What is the scope? Migration or single fix?
- If `1-description.md` has a `## Acceptance criteria` section, extract
  its `AC-n` ids for Steps 5-7 — see `references/requirements-tracing.md`.
- If `4-status.md` ALSO already carries that same section plus a
  `**Round boundary:**` stamp, this is a held-back spec taking another
  round on its open checks, not a first analysis — see
  `references/requirements-tracing.md`'s own "A held-back spec's second
  round" section for how Steps 4-8 below scope to it.

**This skill never modifies anything outside the spec's own four
documents** — not application source, not test files, nothing in the
project repo, by any tool (Edit, Write, Bash included). If Step 6's own
"Recommended solution" reads as obviously correct and ready to apply,
stop anyway: applying it is `/aide-implement`'s job, in its own turn, not
something this skill does on its behalf because it happens to be
possible in the same session.

### Step 2 of 10: Detect complexity

First write `--- Step 2 of 10: Detect complexity — started`, and when this step ends, `--- Step 2 of 10: Detect complexity — done`.


Classify as LOW/MEDIUM/HIGH: Operation, Keywords and API impact decide the
grade, and the grade is the highest band any of them reaches. The number of
files is a signal read last — it never raises a grade the other three read
as LOW. See `references/complexity-and-analysis.md` for the criteria.

### Step 3 of 10: Analyze the codebase

First write `--- Step 3 of 10: Analyze the codebase — started`, and when this step ends, `--- Step 3 of 10: Analyze the codebase — done`.


Search the code from where the wiki pages read in Step 1 point.

Scale the analysis to the complexity:
- **LOW:** Find the file, read it, check tests. < 15 min.
- **MEDIUM:** Find dependencies, related files, API impact. 20-45 min.
- **HIGH:** Search broadly, categorize files, create a migration plan. 1-3 hours.

See `references/complexity-and-analysis.md` for detailed steps per level.

**Where a symbol is used or defined, ask the language server first.**
When an `LSP` tool is listed, it is usually deferred: load it once with
`ToolSearch` (`select:LSP`) before the first search, then make the FIRST
search for where a function, type or constant is used or defined a
`findReferences` or `goToDefinition` call — never `grep`. It answers with
the real references, not every line that happens to contain the name.
Fall back to `grep` only when the language server gives no answer (it
errors, or the file's language has none), and for text that is not a
symbol — a message, a config key, a CSS class.

### Step 4 of 10: Check for work already begun

First write `--- Step 4 of 10: Check for work already begun — started`, and when this step ends, `--- Step 4 of 10: Check for work already begun — done`.


A step stopped by its own time limit still commits what it wrote, and
that work is landed on the default branch rather than left on a branch
nobody can see — so the three files may already hold an
earlier run's answers. Read `specs/XX-slug/2-analysis.md`,
`3-solution.md` and `4-status.md` as they stand before writing anything.

A section is UNWRITTEN when it still holds its template's bracketed
placeholder text: `[not analyzed yet]`, `[filled in by analysis]`,
`[How the analysis was performed...]`, `[not started]`, and any other
bracketed stand-in the templates put there. Anything else is written,
whether an earlier run wrote it or this one did.

Counting headings is not enough. A half-written section carries its
heading exactly as a finished one does, so the heading says nothing
about whether the section was ever filled in — the bracketed
placeholder is the signal, and it is the only one.

Fill in the sections that still hold their placeholder. Leave every
section that already has real content exactly as it stands.

A held-back round (Step 1) is a different case from the above, not a
variant of it: `2-analysis.md`/`3-solution.md` are already fully
written from an earlier round, holding no placeholder at all, and this
round APPENDS a new `## Round N` subsection to each instead of leaving
them untouched — see `references/requirements-tracing.md`.

### Step 5 of 10: Update 2-analysis.md

First write `--- Step 5 of 10: Update 2-analysis.md — started`, and when this step ends, `--- Step 5 of 10: Update 2-analysis.md — done`.


Assemble the complete new text of `2-analysis.md` (sections already
filled in per Step 4 copied verbatim; placeholder sections replaced with
real content), then write it with:

    aide-write-spec --specs-root <specs-root> --folder XX-slug \
      --file 2-analysis.md <<'SPEC_EOF'
    <the complete file text>
    SPEC_EOF

Never use the Write or Edit tool on a spec file — `aide-write-spec` is
the only legitimate path. Follow the spec structure §
2-analysis. Include: Tracking info, mapping, affected files with
file:line, API impact, test coverage.

When Step 1 read the wiki, the `## Mapping` section gets a line **Wiki
pages used** listing each page with its state: `current`;
`changed since its commit — files: <changedFiles>`; `unknown`; or
`hand-written — freshness not tracked`. Without a wiki, no such line.

Sections already filled in per Step 4 are left untouched.

Nothing that judges the solution goes here — complexity, estimate and risk
analysis belong to 3-solution.md (spec structure § Separation of content).

When AC-n ids exist, see `references/requirements-tracing.md` for how
findings are prefixed with the AC-id(s) they support.

### Step 6 of 10: Create the implementation plan (3-solution.md)

First write `--- Step 6 of 10: Create the implementation plan (3-solution.md) — started`, and when this step ends, `--- Step 6 of 10: Create the implementation plan (3-solution.md) — done`.


Assemble the complete new text of `3-solution.md` the same way as Step 5,
then write it with `aide-write-spec --file 3-solution.md` (never
Write/Edit). Follow the spec structure § 3-solution.

Sections already filled in per Step 4 are left untouched.

**Scope:** the files to change, the complexity grade with the factors behind
it, and the estimate for manual and AI-assisted development.

**Behavior delta:** state what the chosen solution ADDS / MODIFIES / REMOVES
in behavior, relative to how the system works today — not just which files
change (those are listed under Scope).

**Risk analysis:** the risks the chosen solution carries, each with
consequence, probability and mitigation.

**Acceptance criteria:** testable given/when/then scenarios. Each criterion
must be verifiable by a test — if you cannot phrase the test, the criterion
is too vague. When AC-n ids exist, see `references/requirements-tracing.md`
for how each criterion opens with the AC-id it covers.

End a criterion with *(browser)* when only a real browser can answer it:
whether something is displayed, where it sits on the screen, what
scrolls, what moves when its text changes. What the markup or the
stylesheet says is not a browser question, and a criterion without the
tag is tested the ordinary way. `/aide-implement` writes a browser test
for every tagged criterion.

**Name the project's test command.** `aide-resolve-test-cmd --project-dir .`
prints it (the manifest's `AIDE_TEST_CMD`, the tools-and-scripts skill,
"Project commands"). Write it into the plan verbatim — never leave the
`<project test command>` placeholder standing.

Structure the plan with TDD:
- Task 0: Write tests (RED phase) — at least one failing test per acceptance criterion
- Task 1-N: Implementation (GREEN phase)
- Testing strategy (VERIFY phase)

Call a plan item a task, never a step: a step is what the queue runs, or
a numbered section of a skill such as this one, and a log that says
"Step 8" must mean one of those.

### Step 7 of 10: Review the plan

First write `--- Step 7 of 10: Review the plan — started`, and when this step ends, `--- Step 7 of 10: Review the plan — done`.


Attack the plan while the mistake is still cheap, before any test is
written: reviewers with distinct perspectives (feasibility, scope,
coherence) attack `3-solution.md`, findings become must-fix/should-fix,
and the plan is REVISED — not just annotated. See
`references/plan-review.md` for the full routine (scaled to complexity,
consolidation, and what gets written where).

Skip this step only when `3-solution.md` is still an empty template —
nothing was written in Step 6 to review.

When AC-n ids exist, see `references/requirements-tracing.md` for the
must-fix check on missing coverage.

### Step 8 of 10: Update 4-status.md

First write `--- Step 8 of 10: Update 4-status.md — started`, and when this step ends, `--- Step 8 of 10: Update 4-status.md — done`.


Assemble the complete new text of `4-status.md` the same way as Step 5,
then write it with `aide-write-spec --file 4-status.md` (never
Write/Edit). Follow the spec structure § 4-status.
- LOW: Simple checklist (< 30 lines)
- MEDIUM/HIGH: Phase-based tracking (50-100 lines)

Sections already filled in per Step 4 are left untouched.

When AC-n ids exist, see `references/requirements-tracing.md` Step 8
for the `## Acceptance criteria` section this file gains — one row per
AC-n id, unticked, for the user the spec is for to judge and tick,
never for this skill or `/aide-implement` to tick themselves.

`aide-run-spec` writes `Workflow steps completed:` from the spec's own
commits — leave that line exactly as you found it. The same script
writes this phase's `Repo`/`Model`/`Result`/`Time spent`/`Cost` block
into `2-analysis.md`'s own Tracking info — leave those lines alone too.

A headless run gets its commit for free — this session does not run
`git commit` or `git push` itself, headless or not. Working
interactively, ASK whether to commit the analysis, and suggest this
message so the step is recognised the same way:

```text
Run /aide-analyze for <spec-folder> (model: <tool> <model>)
```

Add the `(model: ...)` part only when you can name your own model with
certainty. A Claude Code session is told which model it is running in
its own context, so it can write `claude claude-opus-5`; an assistant
that cannot name itself offers the bare subject without the suffix and
never guesses.

Offer it only when the analysis actually completed; one that failed, or
that you stopped part-way, has nothing to record.

### Step 9 of 10: Confirm

First write `--- Step 9 of 10: Confirm — started`, and when this step ends, `--- Step 9 of 10: Confirm — done`.

In a headless run nothing of this is on the default branch yet: the
analyze is finished only once Step 10, the merge into main, is done. So the
report's first line ends `— not finished, the merge into main is next
(Step 10)`, and the report never calls the analyze done or complete.


Show a summary with complexity, number of affected files, the plan
review's verdict (counts of must-fix/should-fix, what was revised), and
the next step.

### Step 10 of 10: Merge into main

Aide writes `--- Step 10 of 10: Merge into main — started` itself, after this session, and ends it `— done` or `— stopped: <why>`.

Not this session's step, and it writes no mark for it. In a headless
run Aide merges what this session committed on the spec's branch into
the default branch once the session has ended, and the analyze is finished
when that merge is, not before. Working interactively there is no such
step: the steps above say what reaches the default branch.

IMPORTANT:
- ALWAYS use the file:line format for references
- ALWAYS consider API impact (frontend ↔ backend)
- Match the scope of the documentation to the complexity
- Code blocks ALWAYS end with just ` ``` `

---

## Next step

```text
/aide-implement 55
```