Clean Delivery Workflow

---
name: clean-delivery-workflow
description: >
  The order of work for a change, and how much of that order a given change actually warrants:
  understanding before editing, clarifying what is ambiguous, deciding the test approach,
  implementing in reversible steps, separating refactoring from behaviour where independently valid,
  running the gates the risk deserves, and verifying before declaring done. Also the entry
  point that routes a situation to the skill that owns it. Use when starting a change and the
  order is not obvious, when a change has sprawled and needs re-sequencing, when refactoring
  and behaviour changes have been mixed in one commit, when work is being declared done
  without verification, when the same ceremony is being applied to a one-line fix and a
  migration, or when you know the problem but not which skill covers it. Does not itself cover
  any step in depth — it routes to requirements-and-acceptance, java-testing-strategy, tdd,
  java-refactoring, code-review and quality-gates, each of which owns its own.
---

# 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). Establish the observable outcome and
   how it will be checked, reusing existing acceptance criteria. 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).
   For multistep work, use the project's plan convention to record increments, their dependencies
   and completion checks. Update completed work, evidence and blockers as each increment finishes;
   revise the remaining sequence when evidence changes. A small change needs no separate plan file.
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). After review fixes,
   rerun checks whose results the edits invalidate, plus any gates required for the final state.
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.** Connect the implemented outcome to observed checks and state what remains
   unverified or deferred. A completed plan or a green pipeline alone does not establish
   that the requested behavior was delivered.

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