Skip to main content

Skip docs navigation
manual page/ Start here

Inventories and change plans

sourceSource: suspec/docs/05-brownfield-and-change-plans.mdModified: 2026-07-13

example.txt

file
inventory -> spec -> change plan -> task split when needed -> implement -> review

Add only the structure the work needs. If you cannot name current behavior, you cannot promise to preserve it. sus-inventory records present reality. sus-change-plan defines a behavior-preserving transformation. Both use the agent-neutral artifact location.

Inventory

Use an inventory when ownership, behavior, tests, interfaces, dependencies, or constraints remain unclear. Record:

  • relevant files and modules;
  • observed behavior and public interfaces;
  • existing tests;
  • constraints and dependencies;
  • unknowns;
  • file or line evidence for every structural claim.

Inventory observes. It does not pitch a redesign. The CLI recognizes inventory but does not check it; review it by hand.

Change plan

Use a change plan for migrations, rewrites, schema changes, broad refactors, dependency upgrades, or staged performance work. It adds:

  • baseline and target state;
  • preservation guarantees;
  • ordered waves;
  • verification per wave;
  • cutover and rollback.

The source spec owns product requirements. The plan owns transformation order and preservation context.

Prefer existing requirement references:

example.yaml

file
preserves:
  - SPEC-checkout#AC-001

Use PG-NNN only for plan-local guarantees. Put lasting behavior in tests, public contracts, or project decisions.

Each wave must leave the codebase usable and verifiable. When a wave becomes a task, that task still names the source spec and its scoped requirement IDs.

suspec check <path> validates preservation references and wave structure.

Live drift

When code or evidence contradicts the working spec, stop. Either intent changed or something is wrong. Update the spec in the first case; fix code in the second. Record any lasting decision through the project's own channel. After close, start later work from current code and durable records, not old transient artifacts.

Skip both documents for local work whose behavior, ownership, and tests are already clear.

Next: tasks. Previous: specs.

Need a starting point? Install the skills