From 8bc2aca5cf20256abf6ee8ef1436532d115e5dd3 Mon Sep 17 00:00:00 2001 From: BuildTools Date: Mon, 25 May 2026 12:52:03 -0600 Subject: [PATCH] Add context hygiene at phase boundaries and abort budget Closes #19 Co-Authored-By: Claude Opus 4.7 (1M context) --- RESEARCH.md | 1 + create-dev-loop.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/RESEARCH.md b/RESEARCH.md index 5bf16b3..3010733 100644 --- a/RESEARCH.md +++ b/RESEARCH.md @@ -110,6 +110,7 @@ Last reviewed: 2026-05-25. **Implementations.** - PR #26 (Promote 'verify each Closes #N' to template Phase 4): shipped 2026-05-25. Observed effect: pending — needs N cycles of data. Narrow application of "re-state scope at boundaries" — verifies issue numbers against actual issue content before push, countering stale-context anchoring. +- PR #32 (Context hygiene at phase boundaries): shipped 2026-05-25. Observed effect: pending — needs N cycles of data. Adds compressed plan/implementation/cycle summaries at the Phase 2 → 3, Phase 3 → 4, and Phase 8 → 9 boundaries, plus an abort-budget edge case (~500 tool calls or ~200k tokens) with a gap-issue template. Implements the second and third bullets of this finding's implications. --- diff --git a/create-dev-loop.md b/create-dev-loop.md index 9a29feb..71cf0f7 100644 --- a/create-dev-loop.md +++ b/create-dev-loop.md @@ -165,6 +165,14 @@ Include `Closes #N` in the PR body for each resolved issue so GitHub auto-closes git checkout -b {{BRANCH_PREFIX}}/ \`\`\` +**Plan summary (re-read at the start of Phase 3).** Before exiting Phase 2, write a compressed plan in this shape: +- **Issues in scope:** `#N`, `#M`, ... +- **Branch:** `{{BRANCH_PREFIX}}/` +- **Files I expect to modify:** path, path, ... +- **Invariants to preserve:** tests pass, no new placeholders without table rows, no fenced code blocks unescaped, etc. (project-specific invariants from CLAUDE.md) + +Phase 3 begins by re-reading this summary. The point is to ground the implementation in a tight statement rather than the full accumulated triage transcript — per RESEARCH.md §4, context rot degrades performance even when the window isn't full. + --- ### Phase 3 — Implementation @@ -203,6 +211,12 @@ git diff --stat origin/{{DEFAULT_BRANCH}} \`\`\` If the diff exceeds **~400 net LOC** or modifies more than **~10 files**, stop and rescope: either drop one of the batched issues from the PR, or split the remaining work into a follow-up PR. Hard stop at **~800 LOC** or **~20 files** — at that size, agent PRs fail to merge at substantially higher rates (RESEARCH.md §2). +**Implementation summary (re-read at the start of Phase 4).** Before pushing, write a compressed implementation summary: +- **Files actually modified:** path, path, ... +- **Commit summary:** one line per commit +- **Test/validation result:** PASS / FAIL — name the command that produced the verdict +- **Open carryovers:** anything in scope that wasn't done and why (becomes input for Phase 9) + --- ### Phase 4 — PR @@ -369,6 +383,12 @@ gh issue close --comment "Resolved in PR #." **Proceed to Phase 9.** Do not stop here — the self-audit is mandatory whether or not anything was implemented. +**Cycle summary (re-read at the start of Phase 9).** After merging, write a compressed cycle summary: +- **Issues closed:** `#N`, `#M` +- **PR(s) merged:** `#X` +- **Surprises:** anything that didn't go as expected (anchor for the self-audit's reflection prompts) +- **Followups filed:** any new issues filed mid-cycle and where + --- ### Phase 9 — Self-audit @@ -426,6 +446,14 @@ git checkout {{DEFAULT_BRANCH}} git push origin --delete {{BRANCH_PREFIX}}/ \`\`\` **Two issues conflict mid-implementation:** finish the further-along one; file a note on the other. +**Cycle exceeds abort budget:** if the cycle's tool calls exceed ~500 or accumulated context exceeds ~200k tokens without converging, abort rather than push through. The half-life model (RESEARCH.md §4) predicts persistence past a budget is strictly worse than restart with fresh context. Steps: +1. Mark the in-flight PR `Draft` (`gh pr ready --undo `) or, if no PR is open, push the branch with a `WIP:` commit so work isn't lost. +2. File a gap issue on `dmccoystephenson/-dev-loop` with title `Abort budget exceeded on ` and body containing: + - **Issues in scope:** the `#N`s the cycle was trying to close + - **Files modified so far:** path list + - **Where convergence stalled:** the last phase reached and what was blocking it + - **Suggested next attempt:** what to try differently on the next run +3. Exit. Do not return to Phase 1 in the same context — restart in a fresh session. **No issues and no improvements found:** report what was checked; end the loop. ```