eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions

Refine C2 Mikado method: failed attempt handling and early PRs

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Erich Blume 2026-02-20 09:43:30 -08:00
commit 08ee70d6df
1 changed files with 18 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

23
docs/how-to/agent-change-process.md
View file

@ -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