Skip to content

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.
How a campaign is put togetherA campaign contains an ordered ladder of phases ending at the end state. Each phase is recognized by its objectives. Sectors of the code stand at the first phase whose objectives still have holdouts in them, and move right, toward the end, as those holdouts are cleared.CAMPAIGNbilling-dddscope src/** · the perimeter (**/context.ts) births one sector per bounded contextPhasesin orderObjectivesdetector + ledgerSectorsholdouts leftPHASE 1domainno-io-in-domainhas-unit-testsPHASE 2repositoryno-raw-querieshas-migrationPHASE 3dual-writehas-flaghas-both-writesPHASE 4cutoverno-flagno-legacy-writeTHE ENDend stateevery objectivemet: no holdouts,numbers at targetlegacy212orders31billing7payments2shippingdonebillingclear the last 7 →billing moves onA sector stands at the first phase whose objectives still have holdouts in it.Clearing them moves it right; the legacy (what no sector has claimed) stands at phase 1.Each objective keeps a ledger of every place its pattern still occurs, per sector. It only shrinks on its own:growth needs a recorded reason, so the counts above can only go down.
A campaign owns an ordered ladder of phases; each phase is recognized by its objectives; sectors climb the ladder as their holdouts reach zero.

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.

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).

Defining phases as you goThe same campaign at three points in time. On day one only the first phase is defined and the rest is an open phase carrying only an intent. As sectors reach the open phase and the team learns, it is refined into defined phases, and a new open phase sits at the edge of what is known. Months later five phases are defined and one open phase remains.Day onefirst step onlyDEFINEDdomainnot known yetOPENintent only“a repository, somehow”Weeks latersectors reached itDEFINEDdomainDEFINEDrepositoryDEFINEDdual-writenot known yetOPENintent only“then cut over?”Months latermostly knownDEFINEDdomainDEFINEDrepositoryDEFINEDdual-writeDEFINEDbackfilledDEFINEDcutoverOPENintent only“aggregates: undecided”learned → refinedlearned → refinedDefined phases are deterministic: detectors, ledgers, a ratchet. The open phase is intent and notes —the edge of what the team knows. Each sector that reaches it teaches the next step, which is then written down.
The plan is written as far as it is known. The open phase moves right as the refactor teaches the team what comes next.

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.

  • 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 its scope adds them.