Introduction
A campaign tracks a refactor too big for one change. Use one to count the remaining work, stop it from growing, and tell whoever edits the code what’s left.
Say your team is moving 140 React class components to hooks. A campaign records all 140,
fails check if a new one appears, and can tell anyone editing a file that still has one.
| Term | Meaning |
|---|---|
| campaign | One refactor, written under campaigns in architecture.yaml. |
| objective | A pattern the code is moving away from (or a thing it must come to have), or a number to reach. |
| ledger | A committed file listing every place an objective still fires; it may only shrink. |
| holdout | One entry in a ledger: a place the refactor has not reached yet. |
| sector | A piece of code that moves through the campaign as one, such as a folder or a file. |
| phase | A named step of the refactor; a sector’s phase is the first one it has not finished. |
| nudge | architecture campaigns status --changed: what the files you touched owe the campaign. |
You never set a sector’s phase. It is the first phase whose objectives still have holdouts in that sector, so progress comes from the code.
Plan only what you know
Section titled “Plan only what you know”The last phase may be open: an intent in prose, with no objectives. Phases before it are
enforced. When you learn the next step, write it as a defined phase. Changing a defined phase
later needs a recorded reason (see Phases).
The smallest campaign
Section titled “The smallest campaign”One objective, no sectors, no phases. Goodbones runs this one on itself:
campaigns: lowering-reports-not-throws: why: "`loadPolicy` returns a `Result`, but a manifest that lowers badly escapes it as a thrown `Error`." how: "Return `Result.fail(new ConfigInvalid({ configPath, detail }))` and let `loadPolicy` pass it up." owner: "@dataquail" scope: ["packages/core/src/manifest/**"] staleAfter: 90d objectives: throws-in-lowering: holdout: match match: all: - path: { file: "\\.ts$", fileNot: "\\.test\\.ts$" } - syntax: { pattern: "throw new Error($$$)" } probes: fires: - path: packages/core/src/manifest/zzprobe.ts source: 'const lower = () => { throw new Error("bad manifest"); };' ignores: - path: packages/core/src/manifest/zzprobe.ts source: "const lower = () => Result.fail(new ConfigInvalid({ configPath, detail }));"Defining a campaign shows the full shape.
A campaign does not
Section titled “A campaign does not”- Rewrite code. Use a codemod for that.
- Run tests, trace runtime behavior or span repositories.
- Change coverage or residue numbers.
- See files the language pack skips (TypeScript walks
.ts,.tsx,.mts,.cts), unless itsscopeadds them.