Software architecture

Goal

The codebase measurably closer to the twelve principles below, or a ranked account of where it is not — every claim tied to a principle file and a path:line, and every change proven behaviour-preserving by the project's own checks.

Context

Find the principle files first. Each one carries the principle, why it holds, what it looks like in practice, how to tell it is being violated, and a ## Pass section giving what to look for, what a safe fix is, and where to stop. Nothing is loaded for you: they are in principles/ inside the skill directory — the path given at the top of this prompt, or the folder holding this SKILL.md.

If that does not resolve, say so once and work from the index below alone. That is the degraded mode: still useful, but cite the index rather than inventing detail, and never invent a thirteenth principle.

The index. One file per principle, numbered in reading order. The numbering is not a ranking — a real decision usually turns on two or three at once.

Steps

1. Pick the mode and state it in one line before touching anything:

   • refactor by default.
   • document when the operator asked for a review or a write-up rather than changes.
   • narrowed when the operator named principles by number or title: run refactor or document over only those.

   In plan mode, survey and judge as usual; the refactor you would make, or the document you would save, is the plan.

2. Survey. In every mode. Say what the scope is — the whole tree, a directory, or a change (git diff, a branch) — before reading. Then:
   • Read what the project has already decided: spec/, ADRs, AGENTS.md, CLAUDE.md, README, docs/. A departure that was chosen deliberately and written down is an answer, not a finding.
   • In refactor mode, learn the build, test and lint commands and run them once before the first edit, so you know which failures you inherited. Document mode changes nothing, so it skips the run.
3. Read the principle files in scope — all twelve, or only the ones selected — before judging anything. Every finding cites the file it came from.
4. Refactor. One principle at a time, in index order, smallest safe change first, inside that file's Safe fix and never past its Stop at. Take the cheap gains: a file the work is already touching is the cheapest chance that file has of coming closer to these. Re-run the project's checks after each principle and confirm the result matches step 2 — a behaviour change is a bug, not a refactor. Anything past Stop at is written up as a proposal instead of done.
5. Document. The same survey with no edits: rank the gaps by what leaving them costs, each with path:line, the principle file, the symptom from that file's "How to tell it is being violated", and the size of the fix. Save it to spec/decisions/NNNN-<short-title>.md if that tree exists, otherwise docs/architecture-review.md.
6. Narrowed runs step 4 or 5 over the chosen principles only, and says which principles were not examined.
7. Name the conflicts. Where two principles pulled opposite ways, say which one gave way and why. Two principles disagreeing is the normal case, not a contradiction to report; that sentence is the reasoning, and it is the part a reader months from now needs.

Constraints

• Never trade behaviour for shape. Every refactor is behaviour-preserving, and the project's own checks are what prove it.
• Do not widen the change you were asked for. Past a Stop at, propose — say what you would do and why, and let whoever is deciding decide.
• Shape only. These principles settle nothing about language, library, naming, formatting, test framework, deployment target or process.
• A recorded decision that departs from a principle has answered the question. What these outrank is a preference nobody wrote down.
• No new dependencies, services, caches, or abstractions. 11-prefer-simplicity.md applies to this skill's own output.

Done when

The mode and scope were stated; every principle in scope was either applied or explicitly deferred with a reason; after a refactor, the project's build, test and lint commands give the same result they gave in step 2; and nothing was changed past a Stop at.

Output

Open with one line: the mode, the scope, and which principles were examined.

Then one section per principle that produced something, in index order:

• Refactor — what changed, as path:line, and why it was safe.
• Document — the gap, as path:line, the symptom, and the size of the fix.

Close with:

• Left alone — what sat past a Stop at, or was blocked, and what would settle it.
• Conflicts — where two principles pulled opposite ways, which gave way, and why.
• Not examined — principles out of scope, when narrowed.