Examples

Phased Coding Workflow

A general workflow for producing correct code on any project, in any language. The core idea: work in numbered phases separated by explicit gates, verify against a written contract rather than against your own memory of intent, and treat every error as a diagnosis problem before it is a fix problem.

Phase 1 - Understand and Plan (no code yet)

1. Restate the task in one or two sentences. If you cannot, you do not understand it yet - ask or re-read before proceeding.
2. Write down the contract: the observable behaviors and invariants the finished code must satisfy (e.g., "value X never goes negative," "operation is safe under concurrent access," "existing behavior Y is unchanged"). These become your test targets and your definition of done. Number them.
3. Identify constraints and non-goals: what must NOT change, what is explicitly out of scope.
4. Decide the order of construction: which unit has no dependencies and gets built first; which units depend on it. Prefer bottom-up so each piece can be checked against already-verified pieces.
5. Make testability decisions NOW, not later: anything nondeterministic (time, randomness, network, environment) should be injectable or isolatable so tests can control it.

Gate to Phase 2: You can list the invariants from memory and state the build order. If any invariant is vague ("should be fast," "should handle errors"), sharpen it into something checkable first.

Phase 2 - Implement in Small Ordered Units

1. Build one unit at a time, in the dependency order from Phase 1.
2. After each unit, do a cheap sanity check before continuing: does it parse/compile, does it import/load, does one obvious happy-path call behave as expected. Do not stack unverified units on top of each other - an error at the bottom multiplies upward.
3. When existing code must be modified, read the surrounding code first and match its conventions. Never edit code you have not read.
4. Keep a running list of anything you deferred, assumed, or noticed as suspicious. Do not trust yourself to remember it.

Gate to Phase 3: Everything you wrote loads/compiles cleanly, and a minimal smoke test of the happy path succeeds. Writing a full test suite against code that fails at load time is wasted work.

Phase 3 - Verify Against the Contract

1. Write one test (or explicit manual check) per numbered invariant from Phase 1. Tests target the contract, not the implementation - ask "what did I promise?" not "what does my code do?"
2. Add adversarial cases: for each invariant, ask "how would a hostile or unlucky caller break this?" (boundary values, empty inputs, oversized inputs, concurrent access, resource exhaustion, repeated/reordered calls). The most valuable test is usually one the implementation author would not think to write - so put on the attacker's hat deliberately.
3. Make time/randomness deterministic in tests using the injection points from Phase 1.
4. Run everything and record the results.

When to write tests vs. manually re-check

Write automated tests when:

• The behavior can be asserted programmatically (return values, state changes, raised errors, file contents).
• The code will be run more than once or changed later (almost always).
• The logic involves boundaries, arithmetic, time, concurrency, or state machines - categories where human eyeballing reliably fails.
• You just fixed a bug: always encode the bug as a test so it cannot silently return.

Manually re-check (read, run once, inspect output) when:

• The output is inherently judged by inspection (formatting, layout, log message wording, generated documents).
• It is throwaway exploration code that will not be kept.
• Writing the test harness would cost far more than the code itself AND the code is trivial and single-use. If it is non-trivial OR will be kept, this exception does not apply - write the test.
• A manual check is a supplement, never a substitute, for tests on logic that a test could cover.

Gate to Phase 4: Every invariant has a corresponding check, and the suite has been run at least once. If everything passed on the first run, be suspicious - confirm at least one test can fail by breaking something deliberately or reviewing that assertions are real.

Phase 4 - Handle Errors and Inconsistencies

When any check fails or something looks wrong:

1. Reproduce it deterministically before touching anything. A bug you cannot reproduce is a bug you cannot verify as fixed.
2. Localize: use the pattern of passing vs. failing checks to narrow where the defect lives before reading code in detail.
3. Diagnose the root cause, not the symptom. State, in one sentence, WHY the failure happens. If you cannot, you are not ready to write a fix.
4. Decide what is wrong: the code or the contract. Sometimes the test encodes a mistaken expectation. Consciously choose which side changes, and say so. Never silently weaken a test to make it pass.
5. Apply the smallest fix that addresses the root cause.
6. Re-run the ENTIRE suite, not just the failing check. Fixes regress neighbors, and first fixes are often wrong. If the same test still fails after your fix, do not patch the patch - return to step 3 and re-diagnose: your causal story was incomplete.
7. If the fix involves a trade-off (fail-open vs. fail-closed, performance vs. safety), document the trade-off where a future reader will see it, and flag it in your summary.

Phase 5 - Final Verification Before Declaring Done

"Tests pass" is necessary, not sufficient. Before calling it done:

1. Re-run the full suite once more against the exact final state of the code (not a state from three edits ago).
2. Re-read the final code fresh, as a reviewer rather than the author. Look for leftover debug output, dead code, inconsistent naming, and comments/docstrings that the fixes made stale.
3. Walk the Phase 1 contract line by line and confirm each invariant is either tested or manually verified. Any invariant with neither is not done.
4. Go through your Phase 2 list of deferrals and assumptions: resolve each or explicitly report it.
5. Report residual risks honestly: known limitations, heuristics, trade-offs, and anything a human reviewer should sign off on. Hiding a known weakness is worse than shipping it documented.

Self-Verification Checklist

Run through this before declaring any coding task complete:

• The contract (invariants + non-goals) was written down BEFORE implementation, and each item is individually checkable.
• Each invariant maps to at least one test or explicit manual check, and I can point to which.
• At least one adversarial/hostile-input case exists per risky invariant (boundaries, concurrency, exhaustion, misuse).
• Nondeterminism (time, randomness, I/O) is controlled in tests.
• Every bug found during the task now has a test that would catch its return.
• For every fix: I stated the root cause in one sentence before writing the fix, and re-ran the FULL suite afterward.
• No test was weakened or deleted to make it pass without an explicit, stated decision that the contract was wrong.
• The final full-suite run happened against the final code state.
• I re-read the final diff/code as a reviewer and removed debug leftovers and stale comments.
• Deferred items and assumptions are resolved or reported.
• Trade-offs and residual risks are documented, not omitted.

Anti-Patterns This Workflow Exists to Prevent

• Starting to code before the definition of "correct" exists.
• Stacking new code on unverified code.
• Testing what the code does instead of what was promised.
• Fixing the symptom, seeing green on one test, and moving on.
• Patching a failed fix instead of re-diagnosing.
• Declaring done at "tests pass" without re-reading the result.
• Quietly dropping a failing test or an inconvenient invariant.