Clean Delivery Workflow

Clean Delivery Workflow

Purpose

Two failures this exists to prevent, and they look nothing alike. The first is the change that starts in the editor: code written before anyone established what was being asked, discovering in review that it solves the wrong problem. The second is ceremony applied uniformly — a one-line configuration fix carrying a design discussion, an acceptance-criteria table and the full pipeline, until the process becomes something people route around.

The workflow establishes prerequisites, not a one-way pass. New evidence can send work back to clarification, risk assessment or test design; how much each step deserves depends on the change.

Workflow

1. Understand. Read the code that exists before proposing a change to it. Find relevant callers, tests, ownership and history. Inspect commits when intent is unclear; “the last three” is not a meaningful boundary when the change history has a different shape. Read applicable repository instructions and build/CI configuration. Inspect staged, unstaged and untracked changes before editing; preserve work outside your ownership. For Java, use the project's compiler/toolchain, runtime and dependency evidence; this workflow sets no Java baseline and does not authorize upgrades or preview features.
2. Clarify. Resolve ambiguity from available evidence first. Ask only for missing decisions that materially change correctness or scope; record safe assumptions and continue independent work (requirements-and-acceptance). Do not invent product constraints.
3. Establish the risk. What breaks if this is wrong, how soon would anyone notice, how hard is it to undo? This one answer sets the test level, the gate set and the review depth for everything that follows.
4. Decide the test approach before implementing: which level, and whether the change is driven by tests or verified after (java-testing-strategy, tdd). For a bug, the reproduction comes first.
5. Implement in reviewable, reversible steps, keeping the tree green where practical. Separate preparatory refactoring from behaviour when each is independently valid and testable. When a safe refactoring exists only to enable the behaviour, preserve the distinction in the diff or commit sequence without manufacturing invalid intermediate states (java-refactoring).
6. Verify. Run repository-required gates plus checks the risk warrants (quality-gates), and read the output. Risk-based selection does not waive a mandatory gate. Not "the build should pass" — what it printed.
7. Review at a depth set by the risk, not by the diff size (code-review).
8. Record what the code cannot say: assumptions, the trade you took, the decision and its alternatives (technical-debt-decisions, architecture-decision-making).
9. Deliver, and say what you did not do — what is out of scope, unverified, or deferred.

Rules

• Understand the affected path before editing it, including under urgency. Revisit earlier decisions when implementation or verification exposes a false assumption.
• Ceremony scales with risk, and risk is not proportional to diff size. A 900-line rename verified by the compiler is a lighter change than a one-character timeout default (references/workflow-by-risk.md).
• Do not start editing to understand. Read first; if the code is genuinely unreadable, that is a finding to report, not a reason to start rewriting it.
• Prefer one coherent change per commit. Separate refactoring from behaviour when the refactoring stands on its own; otherwise optimise for a buildable, reviewable history and make the mechanical and semantic portions explicit. Commit structure is evidence for review and bisection, not a substitute for tests or a universal revert boundary (debugging). Advice about history does not authorize commits, staging unrelated files, rewriting existing history or publication; follow the user's requested delivery boundary.
• Prefer passing checkpoints between reviewable changes; a deliberate failing test during reproduction/TDD is expected. Record pre-existing failures and distinguish them from regressions. Do not weaken tests or discard another contributor's work to obtain green.
• Do not expand the change. Adjacent problems are reported, not fixed, unless the change makes them materially worse or leaving them makes your change wrong.
• "Done" means verified, not written. If a gate could not be run, that is part of the report, not an omission (coding-agent-discipline).
• If something turns out to be blocked, finish everything that is not, and say precisely what was left and why. Silently reducing scope is the failure mode that costs the most trust.

References

• Workflow by risk — references/workflow-by-risk.md. What each step actually collapses to at three risk levels, walked through on a configuration fix, a new endpoint and a schema migration — including which steps disappear entirely and which never do. Read when deciding how much process a change warrants.
• Routing — references/routing.md. Situation-to-skill map across this repository: the craftsmanship skills, the Java language and design skills, testing, concurrency, performance, architecture and operations. Read when you know the problem but not which skill owns it, or when two skills seem to disagree.