afk-architecture-review

Periodic unattended architecture review - find deepening opportunities in money-tracker.online's recently changed code and file at most three refactor issues with a recommendation strength. Use for a

SKILL.md

GitHub

AFK architecture review

These instructions are already in your system prompt. Never call the Skill tool for an afk-* skill - a repo-local skill is not in the agent's registry, so the call fails with Unknown skill.

Adapted from mattpocock/skills improve-codebase-architecture for unattended runs.

  • Scope of changes: read-only on code; the only writes are GitHub issues.
  • Instead of asking the user to pick, each candidate gets a strength, and triage decides.
  • Caps: at most three dispatched children, and at most three issues filed.

0. Setup

Read .ai/skills/afk-codebase-design/SKILL.md and use its vocabulary exactly: module, interface, depth, seam, adapter, leverage, locality. Read CONTEXT.md so candidates use domain names ("the Automation poll module", not "the poller helper"). Read every ADR in docs/adr/. Load .ai/trackers/github.md.

1. Scope: hot spots, not the whole repo

git log --since="30 days ago" --name-only --pretty=format: -- src/ \
  | grep -vE '\.test\.|/test/|__fixtures__|\.md$' | sort | uniq -c | sort -rn | head -15

Pick up to three areas, each a directory or a cluster of files that change together. Leave out areas with an open refactor issue.

Also leave out ideas already declined: search-issues for label:refactor is:closed reason:"not planned" from the last 180 days.

2. Explore

For each area, dispatch one child with cez task create. Tell it:

  • it is read-only: no edits, no commits;
  • to apply the rules of afk-codebase-design;
  • to report through cez task report: the friction found, the candidates with the files involved, and the deletion test result for each.

If dispatch is unavailable, explore the areas yourself, one after another.

Look for friction:

  • understanding one concept means bouncing between many small modules;
  • interfaces nearly as complex as their implementation;
  • logic pulled out for testability while the bugs live in how it is called;
  • modules leaking across their seams;
  • behaviour that cannot be tested through its current interface.

Apply the deletion test to every suspect.

3. Judge

For each candidate, write: Modules, Problem, Proposed deepening (plain English, no interface design yet), Wins (locality, leverage, what tests get simpler), and Strength:

  • Strong: the deletion test concentrates complexity, and the area is a hot spot.
  • Worth exploring: real friction, but the fix involves a judgement call or a risk-high area (see SDLC.md). Settle the judgement call through .ai/skills/afk-decide/SKILL.md (the software architect, plus the security and tenancy specialist for a risk-high area) and file it with the verdict in its Resolved assumptions.
  • Speculative: plausible but unproven. Do not file these; only list them in the run report.

A candidate that contradicts an accepted ADR is filed only when the friction is severe. Then say which ADR it would reopen and why.

4. File issues (at most 3, strongest first)

create-issue titled Deepen <module>: <problem in a few words>. Body:

> *This was generated by AI during a scheduled architecture review.*

## Architecture candidate
**Strength:** Strong | Worth exploring
**Modules:** <module names; key files may be listed here, as this is a finding, not a brief>
**Problem:** <why the current shape causes friction>
**Proposed deepening:** <what would change>
**Wins:** <locality, leverage, test impact>
**ADR conflicts:** <none, or which ADR and why reopen it>

### Resolved assumptions
| # | Question | Applied default | Why |
|---|---|---|---|

Labels: refactor, and a risk label from SDLC.md. The Reconciler then starts a triage run on the issue, so afk-triage writes the brief for Strong and Worth exploring alike. Never write the Agent Brief yourself (ADR 0029).

A security defect is not a refactor candidate and not capped. When you find one (data crossing a tenant or privacy boundary, a missing authorization check, a leaked secret), file it as its own issue labeled security and bug, outside the three-issue cap; the Reconciler then triages it. Never leave one only in the run report.

Done when

At most three issues are filed, none of them duplicates an open or declined one, and the run report lists every candidate with its strength, including the Speculative ones that were not filed.