From c2e8f03e8c765fff297e34e45f92ddd7a5dea7ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivett=20=C3=96rd=C3=B6g?= Date: Wed, 29 Jul 2026 16:50:51 +0200 Subject: [PATCH 1/2] Add Phased Delivery pattern Co-Authored-By: Claude Opus 5 --- documents/patterns/phased-delivery.md | 21 +++++++++++++++++++++ documents/relationships.mmd | 4 ++++ 2 files changed, 25 insertions(+) create mode 100644 documents/patterns/phased-delivery.md diff --git a/documents/patterns/phased-delivery.md b/documents/patterns/phased-delivery.md new file mode 100644 index 0000000..2c63171 --- /dev/null +++ b/documents/patterns/phased-delivery.md @@ -0,0 +1,21 @@ +--- +authors: [ivett_ordog] +--- + +# Phased Delivery + +## Problem +A background agent given a big task in one undifferentiated run produces a monolithic result. Quality issues slip through because the same context that implemented the change also "reviews" it, and the resulting history is impossible for a human to review commit by commit. + +## Pattern +A special case of Background Agent: structure the run into phases, each with its own focus and its own gate: + +1. **Plan** — produce the plan and acceptance criteria; checkpoint it +2. **Implement** — one phase of the plan at a time +3. **Review** — a separate reviewer pass judges the result against your principles and the phase's acceptance gate. Fail → back to Implement with the feedback. Repeat until it passes +4. **Rebase** — rewrite the working history into clean, atomic commits before handing over + +Separate phases work because of focus (see Focused Agent and Feedback Flip): an implementer and a reviewer see different things, even on the same model. The final rebase converts "how the agent got there" into "what a human should review", one atomic commit at a time. + +## Example +A multi-phase work cycle: an implementer sub-agent makes the changes for the current phase only; lint and tests run until clean; a reviewer sub-agent assesses against coding principles plus the phase's acceptance gate; flagged issues loop back to the implementer. Only after the reviewer is happy: commit, then the next phase. The delivery ends with a rebase pass that turns the exploration into a sequence of atomic, reviewable commits. diff --git a/documents/relationships.mmd b/documents/relationships.mmd index b4046f6..8a7b288 100644 --- a/documents/relationships.mmd +++ b/documents/relationships.mmd @@ -81,6 +81,10 @@ graph LR patterns/habit-hooks -->|uses| patterns/hooks patterns/habit-hooks -->|uses| patterns/feedback-loop patterns/habit-hooks -->|uses| patterns/contextual-prompts + patterns/phased-delivery -->|extends| patterns/background-agent + patterns/phased-delivery -->|uses| patterns/feedback-flip + patterns/phased-delivery -->|uses| patterns/focused-agent + patterns/phased-delivery -->|uses| patterns/knowledge-checkpoint patterns/contextual-prompts -->|solves| obstacles/context-rot patterns/contextual-prompts -->|solves| obstacles/selective-hearing patterns/decision-guards -->|solves| obstacles/obedient-contractor From 2f43144b7cfa8fe59c6a2a3f2b7a5f5b6bc14bf3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivett=20=C3=96rd=C3=B6g?= Date: Sat, 1 Aug 2026 20:50:48 +0200 Subject: [PATCH 2/2] Rewrite Phased Delivery pattern Restate the problem around agent focus and position the pattern against Chain of Small Steps, add the verifiability constraint and the goal-check phase, and link the two patterns as alternatives in the graph. --- documents/patterns/phased-delivery.md | 23 ++++++++++++++++++----- documents/relationships.mmd | 1 + 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/documents/patterns/phased-delivery.md b/documents/patterns/phased-delivery.md index 2c63171..cec74fc 100644 --- a/documents/patterns/phased-delivery.md +++ b/documents/patterns/phased-delivery.md @@ -5,17 +5,30 @@ authors: [ivett_ordog] # Phased Delivery ## Problem -A background agent given a big task in one undifferentiated run produces a monolithic result. Quality issues slip through because the same context that implemented the change also "reviews" it, and the resulting history is impossible for a human to review commit by commit. +A big task in a single session leads to a distracted agent. This in turn leads to incomplete work, bugs, and a lack of feedback. One fix to this is the Chain of small steps pattern, but it requires an active human in the loop. In situations when the goal is clear this is not the most effective way to deliver. ## Pattern + +Key constraint: for this pattern to work the goal has to be unambiguously verifiable. Works best when the desired end state is provided rather than the roadmap to get there. + A special case of Background Agent: structure the run into phases, each with its own focus and its own gate: 1. **Plan** — produce the plan and acceptance criteria; checkpoint it 2. **Implement** — one phase of the plan at a time -3. **Review** — a separate reviewer pass judges the result against your principles and the phase's acceptance gate. Fail → back to Implement with the feedback. Repeat until it passes -4. **Rebase** — rewrite the working history into clean, atomic commits before handing over +3. **Review** — a separate reviewer pass judges the result against your principles and the phase's acceptance gate. Fail → back to Implement with the feedback. Repeat until it passes. +4. **Goal check** — a separate agent compares the delivered branch with the goal, and marks any gaps in the original plan. If those gaps exist it re-plans and returns to step 2. +5. **Rebase** — rewrite the working history into clean, atomic commits before handing over + +Notice that this pattern implements an agile team's sprint at the agent level. Critics may call out the lack of feedback, but the feedback is still there at a granular level, it's just shifted to the AI. -Separate phases work because of focus (see Focused Agent and Feedback Flip): an implementer and a reviewer see different things, even on the same model. The final rebase converts "how the agent got there" into "what a human should review", one atomic commit at a time. +The other reason this works is because of focus (see Focused Agent and Feedback Flip): an implementer and a reviewer see different things, even on the same model. + +The final rebase converts "how the agent got there" into "what a human should review", one atomic commit at a time. ## Example -A multi-phase work cycle: an implementer sub-agent makes the changes for the current phase only; lint and tests run until clean; a reviewer sub-agent assesses against coding principles plus the phase's acceptance gate; flagged issues loop back to the implementer. Only after the reviewer is happy: commit, then the next phase. The delivery ends with a rebase pass that turns the exploration into a sequence of atomic, reviewable commits. + +This technique has been used in various contexts effectively: +- Porting legacy applications (for example COBOL financial systems) to modern languages +- Implementing systems that need to follow clear regulatory guidelines. +- Turning vibe coded prototypes into production ready systems (mostly for startups) +- Migration projects that swap one technology for another (i.e. migrate from Angular to React) \ No newline at end of file diff --git a/documents/relationships.mmd b/documents/relationships.mmd index 8a7b288..df6541e 100644 --- a/documents/relationships.mmd +++ b/documents/relationships.mmd @@ -85,6 +85,7 @@ graph LR patterns/phased-delivery -->|uses| patterns/feedback-flip patterns/phased-delivery -->|uses| patterns/focused-agent patterns/phased-delivery -->|uses| patterns/knowledge-checkpoint + patterns/phased-delivery <-->|alternative| patterns/chain-of-small-steps patterns/contextual-prompts -->|solves| obstacles/context-rot patterns/contextual-prompts -->|solves| obstacles/selective-hearing patterns/decision-guards -->|solves| obstacles/obedient-contractor