System Change Engineering

Engineer System Change

Treat every proposed change as a hypothesis about a real system, not as an implementation checklist. Establish whether the change should exist before designing or building it, then keep the solution and the process proportional to the risk.

Preserve the Task Boundary

• If asked only to assess, review, or plan, make no project or external-state changes.
• If explicitly asked to implement, including after an assessment, pass the decision gates before editing and verify the result afterward.
• Treat implementation permission as separate from permission to commit, push, deploy, publish, or update issues and pull requests.
• If repository truth matters, inspect the current target revision and relevant discussion. Do not rely on a stale checkout, an RFC alone, or remembered architecture.
• Separate verified facts, inferences, and unknowns. Do not turn missing evidence into a confident conclusion.

Apply the Decision Gates

1. Ground the Problem

• Trace the current user workflow, failure, or code path before proposing a solution.
• State the undesirable observable behavior and the invariant or outcome that should replace it.
• Identify who is affected and which concrete decision or action changes.
• Check whether the existing system, configuration, documentation, or operating procedure already solves the problem.
• Enumerate adjacent product paths and workarounds, not only the proposed target surface. Explain precisely which accepted outcome each alternative fails; do not claim “the only option” from one missing UI control or code path.
• Treat an absent field, interface, abstraction, or standard as an observation, not proof of a requirement.

Return STOP only when evidence affirmatively shows that no change is needed or the affected workflow already achieves the outcome. Return NEEDS_EVIDENCE when an unverified fact prevents the decision.

2. Name Semantic Consumers

For every proposed durable field, event, API, table, store, module, service, or workflow, establish:

Accept a proposed consumer only when it is tied to a verified current need and committed integration in the same change. Do not accept a roadmap, possible future evaluator, generic read/debug API, storage alone, or “future flexibility” as a semantic consumer. If an addition has no such consumer, remove or defer it. Treat a public or externally consumed contract as a compatibility boundary even when no in-repository caller is visible. Absence of a discoverable caller is uncertainty, not proof that no consumer exists.

3. Choose the Smallest Sufficient Change

Consider solutions in this order and stop at the first one that fully satisfies the verified outcome and invariants without shifting disproportionate recurring cost, coupling, or risk downstream:

1. No product or code change
2. Documentation, configuration, or operating procedure
3. Reuse an existing capability
4. Make a local behavior fix
5. Extend an existing abstraction
6. Introduce a new abstraction
7. Introduce a new subsystem or migration path

• Minimize concepts, states, interfaces, irreversible decisions, and maintenance surface, not literal line count.
• Require a second current consumer, a demonstrated variation, or a hard boundary before generalizing a local solution.
• Prefer independently reversible slices over a comprehensive architecture rollout.
• Distinguish a real problem from an oversized solution. A valid verdict is: “The problem is real; reduce the proposal to this smaller change.”
• Apply these gates recursively to your own recommendation. Do not propose a new field, contract, abstraction, migration, or validation system without naming its consumer, checking existing mechanisms, and showing why a smaller change is insufficient.

4. Map Consequences and Verification Proportionally

Inspect only relevant dimensions, but do not omit a dimension merely because the proposal omits it:

• callers and downstream consumers
• API, data, event, and UI contracts
• authorization, ownership, privacy, and trust boundaries
• persistence, migrations, replay, and side effects
• concurrency, ordering, retries, idempotency, and failure recovery
• compatibility, dependencies, performance, deployment, and operations
• observability and rollback

For state replay or retry features, explicitly distinguish restored application state from external side effects that cannot be undone. Label material risk claims as VERIFIED, INFERENCE, or UNKNOWN. Use an inference to request a focused check, not to require new architecture as though the claim were already proven. Evidence labels classify individual claims; verdicts classify the overall decision. An UNKNOWN requires NEEDS_EVIDENCE only when the unknown blocks a material decision.

Before implementation, require observed evidence for the current-system claims that justify the decision and a proportional, executable verification plan. Treat proposed checks as a verification plan, not observed evidence.