Record reversible decisions with their rationale and cost

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

An approved local plan alternates normalizeRow/normalizeRecord while its spec defines the same behavior and only internal callers are affected. Make a reversible naming choice reviewable rather than deriving publish/security permission from adjudication.

Mechanism

Verify spec/interface/impact and distinguish implementation choice from unsettled product requirements. Record chosen name, evidence, affected callers and rework if wrong; update docs/checks. Preserve rationale in final delivery even after scratch cleanup. Material unknown/out-of-scope decisions follow their own rules.

Bad example

Choose normalizeRow silently, leave docs inconsistent and delete the only record before delivery.

Good example

Within authorized local scope unify the teaching name as normalizeRow, recording spec basis, synonymous normalizeRecord occurrences and callers. Update docs/verify unchanged behavior. Explain that a different naming decision requires coordinated interface/caller/doc changes, not behavior change. Include rationale/checks in final reporting without deleting its sole evidence or publishing automatically.

Why the change matters

Reversible decisions support progress; persistent reasons expose them to correction. Rework scope identifies affected commitments instead of making a choice appear inevitable.

Observable expectation

An illustrative record contains choice/basis/callers/checks/rework and survives into handoff. Inspect consistent naming and avoid invented duration estimates.

A choice alone without reasons/impact is insufficient.

Limits

Cost can be rework objects rather than numbers; unknown time stays unknown. This does not authorize unresolved product/security/destructive/external decisions or importing source auto-adjudication beyond current scope.