From 08ee70d6df67e93d1879f643c028c2dc3d132abc Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Fri, 20 Feb 2026 09:43:30 -0800 Subject: [PATCH] Refine C2 Mikado method: failed attempt handling and early PRs Lessons learned from first C2 attempt (deploy-authentik): - When an attempt fails, reset code changes before committing cards - Cherry-pick doc commits onto clean base if code/docs got mixed - Open a PR early so the user can review the Mikado graph evolving Co-Authored-By: Claude Opus 4.6 --- docs/how-to/agent-change-process.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/how-to/agent-change-process.md b/docs/how-to/agent-change-process.md index b478f6d..7e862c7 100644 --- a/docs/how-to/agent-change-process.md +++ b/docs/how-to/agent-change-process.md @@ -49,16 +49,28 @@ Like C1 but designed to survive agent context loss across sessions: 1. **Goal card:** Create a how-to doc in `docs/how-to/` describing the desired end state - Add `status: active` to frontmatter -2. **Attempt the change**, amending the working commit. On failure, revert the broken change and: - - Create/update prerequisite cards as how-to docs with `status: active` +2. **Attempt the change** — GitOps may require pushing code to test (e.g., ArgoCD sync). When the attempt fails: + - **First**, reset the failed code changes (the branch should not carry broken code forward) + - **Then**, create/update prerequisite cards as how-to docs with `status: active` - Add `requires: [prerequisite-stem, ...]` to the goal card's frontmatter - - Commit the doc updates (the documentation IS the Mikado graph) + - Commit only the doc updates (the documentation IS the Mikado graph) 3. **Work leaf nodes first** — cards with `status: active` and no unmet `requires` -4. **New agent sessions** pick up state by running `mise run docs-mikado` -5. When a card's change succeeds, remove `status: active` (or the entire field) from its frontmatter +4. **Re-attempt the goal** after leaf nodes are resolved — code from the attempt comes back here +5. **New agent sessions** pick up state by running `mise run docs-mikado` +6. When a card's change succeeds, remove `status: active` (or the entire field) from its frontmatter Documentation IS the Mikado graph. Each card captures what was learned from failed attempts, so the next agent session doesn't repeat mistakes. +### Handling failed attempts + +When an attempt fails and you discover prerequisites, the branch must be cleaned up before documenting what you learned: + +1. Reset to before the code attempt (`git reset --hard`) +2. Commit the new prerequisite cards and frontmatter updates +3. If you already committed docs mixed with code, cherry-pick the doc commits onto a clean base rather than reverting (avoids noisy add/revert history) + +The branch between attempts should contain only documentation. Code returns when prerequisites are satisfied and the next attempt succeeds. + ## Card Conventions ### Frontmatter @@ -89,6 +101,7 @@ tags: ### Git Discipline - Single feature branch per C1/C2 change +- **Create a PR early** — open a draft PR after the first doc commit so the user can review the Mikado graph as it evolves between iterations. Push doc updates after each attempt cycle. - Amend a single working commit as you iterate; keep the branch history clean - GitOps requires pushing to test — if a pushed commit breaks, revert it promptly - Commit doc updates noting what was learned from failures