agentleFS
eisbaweisbaw/mped-skills/skills/phase3-backlog-ralph/SKILL.md

phase3-backlog-ralph

Skill11 starsChanged 3 months agoMITView on GitHub

Autonomously work through a backlog / task list, implementing tasks with commits and review. Use when the user asks to "implement the backlog", "work through the tasks", run a long autonomous build loop, or "/loop"-style continuous task execution. An orchestrator loop: dependency-ordered task selection, one heavily-onboarded implementer subagent per task, a TIERED review gate (lightweight for feature cycles, deep multi-reviewer only for irreversible surfaces and scheduled checkpoints), functionality-first velocity with hardening deferred to a wave against stabilized surfaces, strict honest-failure discipline, and the tracker as durable state. Generalises the "Ralph" agentic loop with separated implementer / reviewer / memory roles.

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. About 0 are common, 18 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈18

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do NOT use for a single quick edit, or when there is no task tracker and no test/build gate to anchor honesty.

    line 88
  2. Distinctive:

    Reviewer subagents: read-only, run in parallel — but only at the DEEP gate (irreversible-labeled tasks, scheduled checkpoint tasks, or …

    line 104
  3. Distinctive:

    Exactly one implementer at a time, in sequence: Never run two implementer subagents concurrently — one task, one implementer, then review, …

    line 156
  4. Distinctive:

    Do not descend the ladder while an actionable rung above it remains: clearing rung 4/5 work while rung 1–3 waits is cornerstone-avoidance …

    line 198
  5. Distinctive:

    Before briefing, the orchestrator itself reads the task and locates the relevant spec/PRD section and the closest existing-code/test …

    line 220
  6. Distinctive:

    Onboarding steps, ordered: read the spec/PRD section(s) relevant to the task.

    line 229
  7. Distinctive:

    Every gate run — pass or fail, FAST or BROAD — appends to the HEAD commit's git notes.

    line 323
  8. Very specific:

    Use a dedicated ref (--ref=verification) so notes never collide with other tooling, and remember notes are not pushed by default — if the …

    line 347
  9. Distinctive:

    If the cycle revealed a durable, non-obvious fact (a constraint, a contract gap, a workflow gotcha), persist it to long-term memory so the …

    line 361
  10. Distinctive:

    Run the full verification gate before every commit.

    line 398
  11. Distinctive:

    Commit per logical unit. Match the repo's existing commit conventions (message style, no AI/co-author credit if the project forbids it, …

    line 406
  12. Distinctive:

    Never hide a gap.

    line 414
  13. Distinctive:

    Never fake success; never implement a workaround in place of a root fix.

    line 415
  14. Very specific:

    Don't stage unrelated/secret/local-only untracked files.

    line 418
  15. Distinctive:

    Every cycle should normally *grow* the tracker.

    line 428
  16. Distinctive:

    If a prior "Done" is found to rest on an overclaim (a comment that lies about the code, an unproven "robust", a flaky test sampled once as …

    line 456
  17. Distinctive:

    Subagent cycles are expensive: don't spawn one per trivial task.

    line 483
  18. Distinctive:

    When the To-Do set nears zero, or every remaining task is environment- blocked / future-milestone scaffolding, do not declare victory and …

    line 489
  19. Distinctive:

    NOT fire the first time the feature list empties.

    line 521
  20. Distinctive:

    Stop and give a status + recommendation when ANY of:

    line 530

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

phase3-backlog-ralph

The third and final phase of the project lifecycle trilogy:

phase1-prd-grill (idea → PRD) → phase2-backlog-snowball (PRD → test-grounded backlog) → phase3-backlog-ralph (backlog → shipped, reviewed code).

Phase 3 executes the backlog phase 2 produced, against the test-grounding phase 2 defined. It is a disciplined Ralph loop: "Ralph" = re-run the same intent until the work is done; the discipline is that claims are backed by green gates and honest reports, and the surfaces where a bug is irreversible get independent review before they count — while everything else ships at feature velocity and is audited by the scheduled hardening wave.

Functionality first, hardening second (velocity doctrine)

Implementing while hardening is too slow, and hardening tentative code is waste: a surface that may still be rewritten makes every polish pass, edge-case suite, and wording audit on it disposable. So the loop runs two distinct modes and never mixes them:

  • Feature mode (the default): ship working functionality behind the acceptance signal (build/test/e2e green, ACs met). No deep review, no polish passes, no exhaustive edge hunting. Findings and known-imperfect choices are FILED as hardening tasks, not fixed now.
  • Hardening mode (scheduled, later): deep review passes, fuzzing, edge/property enlargement, doc validation — run as their own wave (see "Backlog maturity / endgame") against surfaces that have STABILIZED (feature-complete for the wave, or frozen).

Lock in each feature with a biting test as it lands — the one rigor that is NOT deferred. Feature mode defers deep rigor (fuzzing, property tests, edge exhaustion, adversarial verification), but it does NOT defer a feature's own acceptance test. A task marked Done must carry at least one test proven to bite by mutation: shown to FAIL without the change (red) and PASS with it (green), ideally end-to-end. A test that stays green whether or not the feature is correct is decoration, not insurance — and silent AI-regression of an undertested feature is the exact failure this catches. Hold the balance: too much rigor on still-tentative code ossifies it (every rewrite drags a wall of disposable tests); too little lets features break subtly and silently later. Lock in verified-working features with biting tests as they land; defer only the deep-rigor wave. This is a feature-rung activity — the deep "prove every guard bites" negative suite is still hardening-rung work.

The one exception — where rigor is NOT deferred: tasks phase 2 labeled irreversible (on-disk/wire formats about to freeze, data-integrity writers whose bug destroys user data, published APIs, migrations). An irreversible mistake shipped fast is slower than any review. These get the deep gate (below) before they count. If the backlog lacks the labels, the orchestrator classifies at step 0 using the PRD's irreversibility map — and classifying everything as irreversible is the anti-pattern that recreates the slow loop this doctrine replaces. For a tentative/experimental project, phase 2 planned only the current wave and ended it with a self-describing re-plan task whose own description instructs re-invoking phase2-backlog-snowball for the next wave. When task selection (loop step 0) reaches that task, treat it as a phase-boundary, NOT an implementation task: do not brief an implementer to write code — instead invoke phase2-backlog-snowball per the task's own instructions, then resume this loop on the wave it produces. The loop-back is carried in the task, not assumed.

When to use

  • "Implement the backlog / the rest of the tasks", "keep going through the tasks", autonomous multi-task build sessions, /loop-style execution.
  • Any time the unit of work is "a tracked task with acceptance criteria" and there is (or can be) a verification gate.

Do NOT use for a single quick edit, or when there is no task tracker and no test/build gate to anchor honesty.

Roles (keep them separate — this separation is the whole point)

  • Orchestrator (you, the main thread): selects tasks in dependency order, briefs implementers, runs the review gate, applies small review-driven fixes, owns cross-task memory, decides when to stop.
  • Implementer subagent: one per task. Implements, commits, records progress in the tracker. Never self-certifies. Use the mped-architect agent type as the implementer — it is the agent that, with heavy onboarding + explicit benign framing, reliably implemented and committed in practice (a generic implementer agent tends to refuse code edits in this setup). If mped-architect is unavailable in a given project, fall back to the closest architecture-capable general agent, but keep the heavy onboarding.
  • Reviewer subagents: read-only, run in parallel — but only at the DEEP gate (irreversible-labeled tasks, scheduled checkpoint tasks, or orchestrator suspicion), NOT after every feature cycle — qa-test-runner (build/test/lint/e2e gate, actual numbers) and mped-architect (architecture / standards / honesty review); add a cross-model reviewer (e.g. codex CLI, read-only sandbox) on data-integrity surfaces — model diversity has overturned same-model GO verdicts in practice. Read-only agents are far less prone to code-edit refusal. (Same mped-architect agent type as the implementer, here invoked read-only — that is fine and intended.)
  • Direction consultant (advisory, optional): compass-project-direction-consultant (COMPASS) — a read-only project-direction advisor. It sweeps the whole backlog by headline, digs into the top candidate tasks, and returns an advisory sequencing recommendation on the growth ladder (step 0). It runs as a subagent and advises only — it never selects, implements, or gates. The orchestrator weighs its input against dependencies, live gate state, and the user's steer, and remains the sole selector. Consult it at wave boundaries, session start, or when the next direction is genuinely ambiguous — not every cycle (it is expensive, and the ladder usually decides on its own).

The orchestrator is reviewer-of-record and memory. The implementer is hands. They are different agents on purpose: it is the structural check against context fatigue and overconfidence. COMPASS influences what gets selected; it never overrides the orchestrator's authority to select.

Delegation is how the orchestrator's context stays small — so do NOT stop for "context fatigue" while work is still delegable. Every heavy activity runs in a fresh subagent context, not the orchestrator's window: implementation (implementer subagent), gate execution (spawn a qa-test-runner to run build/lint/test and return the numbers — do NOT re-run suites or read long build logs in your own window to "verify"), review (mped-architect / cross-model, read-only), and fixing (send findings back to the SAME implementer via a resume message; don't hand- edit in-thread beyond a trivial one-liner). Done this way the orchestrator's window only accumulates compact verdicts + tracker state, so it grows slowly and "context is thin" almost never fires. When you feel context pressure, the first move is delegate harder (offload the gate/review/fix you were about to do yourself), NOT hand off or pause. A "deep/high-regression-risk keystone that warrants a fresh context" is a reason to spawn a fresh implementer for it — spawning one is the SOLUTION, not a tradeoff to avoid. Stopping for context is a last resort, justified only when the orchestrator's own irreducible reasoning (task selection, verdict reconciliation) is degrading — which is rare precisely because everything expensive is delegated. Never do verification in your own window and then cite the resulting context load as a reason to stop: that is self-inflicted, and it is the specific anti-pattern this loop exists to prevent. The backlog is finished by delegating through it, not by the orchestrator personally having spare context.

Exactly one implementer at a time, in sequence. Never run two implementer subagents concurrently — one task, one implementer, then review, then the next. Only the read-only reviewers run in parallel (they cannot conflict because they do not write). Parallel implementers produce merge races, contradictory commits, and unreviewable diffs; serialise them without exception.

The loop

Repeat until a stop condition (below) is hit:

0. Pick the next task

  • Walk the dependency graph, not the ID order. Choose the highest- leverage unblocked, actionable task (an unblocked keystone beats five trivial leaves).
  • Priority ladder — among unblocked tasks, select in this order. It is a de-risk-early strategy: first build the ability to judge, then attack what is most likely to be wrong, then integrate, then make it rigorous, then make it wide.
    1. Verification & infrastructure first. The oracles, test harness, fixtures, gates, measurement instruments — anything that lets you TRUST a later result. You cannot honestly judge a capability you have no way to verify, so the machinery that judges comes before the thing judged. (Phase 2 should have grounded this; where it is missing or unbuilt, build it before the features that lean on it.)
    2. The hardest core problems next. Attack the load-bearing, highest- uncertainty, most-likely-to-be-wrong core capabilities early — the ones whose failure would invalidate everything stacked on them. Finding a showstopper early beats finding it after ten things depend on it. Hard / risky / env-heavy / deep is a cue to DELEGATE (fresh implementer + guardrails), never to defer in favour of easy work.
    3. Compose them together. Integrate the de-risked core pieces into the end-to-end whole and prove the seams — composition is itself a cornerstone (an integration bug is a real bug); this is where "does it actually work together" gets answered.
    4. Then fuzzing & rigour. Once the composed system is stable, apply the deep gate: fuzzing, property/invariant tests, adversarial verification, "prove the check bites" negatives (the hardening wave — see Backlog maturity / endgame).
    5. Finally broaden & deepen. Widen coverage (more cases, inputs, platforms) and deepen (edge exhaustion, docs validation, polish) last — breadth belongs over a proven, rigorous core, not a shaky one. Do not descend the ladder while an actionable rung above it remains: clearing rung 4/5 work while rung 1–3 waits is cornerstone-avoidance (an anti-pattern below). Dependencies still gate everything — a blocked higher-rung task yields to an actionable lower-rung one, and you note the inversion so it is revisited the moment it unblocks.
  • Optional COMPASS consult (advisory, not binding). At a wave boundary, at session start, or when the right next move is genuinely ambiguous, spawn compass-project-direction-consultant (COMPASS) for a backlog-headline sweep plus a deep-dive on the top candidates. It returns a rung map, structural flags (mis-prioritised cornerstones, stale/blocking deps, cornerstone-avoidance, domain-coherence risks), and an advisory "next N". Treat it as influence, not instruction — it cannot see live gate state, the user's latest steer, or remaining budget. Fold what survives your own judgement into the pick; dependencies remain hard constraints and you remain the selector. Do not consult it every cycle: the ladder above usually decides, and a consult per trivial task is waste. It advises direction; it never runs the gate or marks a task.
  • Skip tasks blocked by the environment (missing toolchains, future- milestone placeholders). Don't burn a cycle proving they're blocked unless that triage is itself the valuable output.

1. Brief the implementer subagent (mped-architect; heavy onboarding — top success factor)

Before briefing, the orchestrator itself reads the task and locates the relevant spec/PRD section and the closest existing-code/test template, and hands those exact paths to the implementer — "read the relevant spec" is unactionable without the pointer.

The implementer prompt MUST contain:

  • Plain framing that the codebase is benign and normal implementation is expected. This preempts the common failure where a freshly-spawned implementer refuses code edits citing a safety reminder. State it first.
  • Onboarding steps, ordered: read the spec/PRD section(s) relevant to the task; read the tracker task in plain/AI-readable mode; read the existing code/tests that are the closest template.
  • Carried context: the architectural facts/invariants/prior-fix knowledge the orchestrator has accumulated across cycles, so the implementer doesn't rediscover or contradict prior work.
  • The verification gate, explicitly (the project's test + build + lint + e2e commands, how to run them — incl. any required dev shell — and the project's bit-identical / acceptance signal).
  • Workflow rules (see "Implementer contract" below).
  • Deliverable shape: a precise report — what landed, commit hashes, actual gate numbers, per-AC status, follow-ups filed, honest limits.

2. Implementer executes (autonomously)

Per the contract. It must be free to return a precise BLOCKED outcome instead of faking completion — a correct "blocked, here is the exact cause, here are the filed prerequisites" is a successful cycle.

3. The gate — tiered, not uniform

Pick the tier at step 0, when the task is selected:

  • LIGHT (default, feature cycles): the implementer's own full verification-gate run (build/lint/test/e2e, actual numbers in its report) plus an orchestrator sanity pass over the report and diffstat (does the claim shape match the diff? any smell of fake green?). No reviewer subagents. The cycle closes on that; the hardening wave will audit this code later, when it has stabilized.
  • DEEP (exception): for tasks labeled irreversible by phase 2 (format freeze, data-integrity writers, migrations, published APIs), for scheduled review-checkpoint tasks, and when the orchestrator smells something (gate flake, a report that doesn't add up, a prior overclaim from the same area). Spawn qa-test-runner and mped-architect (read-only) in one message; add the cross-model reviewer on data-integrity surfaces. Give each: the commit range, what to verify, the invariants, and "do not modify code; return prioritized findings + GO/NO-GO with actual numbers". Re-run flaky-sensitive checks ≥2×. A deep-gated task is not Done without GO.

Escalate LIGHT → DEEP freely when suspicious; never silently de-escalate a task phase 2 labeled irreversible.

Review depth and gate cost are two different dials. The tiers above choose who reviews. This chooses how much of the suite runs, and it is a separate decision:

  • FAST gate (every cycle, non-negotiable): build, lint, unit + integration tests, docs checks, supply-chain, e2e smoke. Minutes. A cycle never closes without it.
  • BROAD gate (cadence, not per-cycle): sanitizers, model checkers, fuzzing — anything that rebuilds the world. Run it once every few landed tasks, at a wave boundary, and before any release or handoff.

The reason is arithmetic, not impatience. Sanitizer recipes typically build the standard library from source per sanitizer (-Zbuild-std, distinct RUSTFLAGS), so their artifacts can share nothing with the normal build or with each other. One "full gate" can therefore be four complete builds. Run that on every re-verification pass — and a single task easily has four — and the loop spends most of its wall clock rebuilding core to re-check a doc edit.

Two hard rules on this dial:

  • Never buy speed by deleting coverage. The fix is persistent per-sanitizer target directories and a sane cadence, never a gate that skips things. If caching was disabled to work around a real defect (stale artifacts, baked-in build environments), that defect is a task — a cache that shipped disabled is the same species of debt as a control that shipped unwired, and it bills you on every run.
  • A cycle that ran only the FAST gate must say so. "Gate green" with the broad suite unrun is an overclaim. Record which tier actually ran (see below); the tracker and the commit trail must never imply sanitizers passed on a run that never invoked them.

4. Findings go to the hardening backlog, not into the cycle

  • Gate-breaking only (the build/test/e2e gate is red, or a claim in the tracker is false): fix in-thread or send back to the implementer now — a red gate or a lie never rides.
  • Everything else — doc wording, extra assertions, edge-case gaps, refactor niceties, "should also handle X" — is FILED as a task labeled for the hardening wave and left alone. Do not polish a surface that may still move; the hardening wave fixes it once, against stable code. (On a DEEP-gated task, correctness findings are gate-breaking by definition — an irreversible surface ships fixed, not filed.)
  • A NO-GO is not "revert" by default — it is "the claim was wrong, make it true or make it honest", then re-verify.
  • The orchestrator does not transcribe the implementer's claimed gate numbers into the tracker as independently verified. On LIGHT cycles record them as the implementer's report; numbers recorded as verified fact are ones a reviewer (or the orchestrator) actually re-ran.

4b. Record the gate in git notes (verification provenance)

Every gate run — pass or fail, FAST or BROAD — appends to the HEAD commit's git notes. The commit message says what changed; the note says what evidence exists that it works. Months later, git log --notes is the only place that answer survives.

git notes --ref=verification append -m "$(printf '%s\n' \
  "gate: FAST | 2026-07-28T14:02Z | exit=0" \
  "ran: fmt clippy test test-node docs-check audit deny e2e-smoke" \
  "skipped: miri asan tsan (BROAD cadence, last run <sha>)" \
  "tests: 1389 passed / 0 failed; transport 43/43")"

Non-negotiables, because a provenance trail that can lie is worse than none:

  • Failures are recorded too. A note trail containing only successes is a marketing document. A red gate, a NO-GO, a stalled reviewer, a crashed sanitizer — all get a note.
  • Record the captured exit code, never an inferred one. If no exit code was captured, the note says exit=UNKNOWN and the run does not count as verification.
  • Name what was skipped, not only what ran. "gate green" without the skip list is the overclaim this whole mechanism exists to prevent.
  • A note is not a substitute for a gate. Writing the note is the last step of verifying, never a way to assert verification happened.
  • Use a dedicated ref (--ref=verification) so notes never collide with other tooling, and remember notes are not pushed by default — if the remote should carry them, push the ref explicitly.

Cheap to write, and it makes the honest-failure discipline auditable by someone who was not in the room.

5. Record in the tracker (durable state)

Tracker-CLI only; never hand-edit task files. Each task carries Plan, progress Notes, Final Summary. New follow-up tasks + dependency edges ARE the evolving graph. Commit the tracker changes so a fresh session resumes with zero loss.

6. Update cross-task memory + feed lessons forward

If the cycle revealed a durable, non-obvious fact (a constraint, a contract gap, a workflow gotcha), persist it to long-term memory so the next cycle/session inherits it. Then do the lessons feed-forward (below) — this is not optional bookkeeping, it is how stateless subagents stop repeating each other's mistakes.

Lessons feed-forward between subagents (critical — subagents are stateless)

Each implementer subagent starts cold with zero memory of prior cycles. Knowledge that does not get written into durable state is lost. So:

  • On finishing a task, the implementer MUST record the gotchas and subtleties it hit — non-obvious invariants, sharp edges, "this looks right but isn't", build/test quirks, why an approach was rejected — in that task's tracker notes / final summary. Not a diary; the things the next person would otherwise re-learn the hard way.
  • The implementer SHOULD feed those forward as constructive notes into still-TODO future tasks that the lesson bears on — via the tracker CLI, appended to the target task's notes, clearly marked as a forward-carried lesson from task <id>. E.g. "from TASK-X: the config loader silently lowercases keys, so any case-sensitive lookup downstream must normalise first." Prefer adding the note to the specific dependent task over a vague global note.
  • The orchestrator folds the same lessons into the carried-context block of subsequent implementer briefs, so the next subagent is told the relevant gotchas up front rather than discovering them.
  • Brief every implementer to read the forward-carried notes already on its task as part of onboarding (step 1), and to act on them.

The test: a fresh subagent picking up task N two sessions later should inherit the hard-won knowledge of tasks 1..N-1 without re-deriving it.

Implementer contract (put this in every implementer brief)

  1. Set the task in progress and assign it to yourself; write an Implementation Plan into the tracker; do not ask the user questions; do not wait for plan approval; proceed.
  2. Run the full verification gate before every commit. Bit-identical / acceptance-signal regressions are hard failures unless explicitly, defensibly justified. If CI carries static checks the local gate cannot run (header/license/SPDX validation, lint that needs an absent submodule, etc.), replicate them as a STANDALONE local recipe so the same failure is caught before push — a green LOCAL gate is not proof of a green CI pipeline. After a push, verify the MR pipeline actually went green before declaring the cycle Done.
  3. Commit per logical unit. Match the repo's existing commit conventions (message style, no AI/co-author credit if the project forbids it, commit-don't-push unless told).
  4. --append-notes progress as you go; --final-summary + mark Done only if every acceptance criterion is genuinely met and verified; otherwise leave it In Progress with honest notes.
  5. Any stub, shortcut, shortcut-considered, or newly discovered issue → file a new tracker task and reference it in code comments + notes. Never hide a gap.
  6. Never fake success; never implement a workaround in place of a root fix; report actual gate numbers; if blocked, state exactly what and why and file the prerequisite task(s).
  7. Don't stage unrelated/secret/local-only untracked files.
  8. On finishing: record the gotchas, subtleties, and rejected approaches you hit in this task's notes/final-summary; and append the lessons that bear on still-TODO future tasks to those tasks' notes, marked "forward-carried from <this task id>" (see "Lessons feed-forward"). Also read any forward-carried notes already on your task during onboarding and act on them.

New tasks are the default output, not an exception

Every cycle should normally grow the tracker. Treat the backlog as the project's working memory:

  • Any found blocker → file a precise prerequisite task with a dependency edge, and point the blocked task at it. Never just narrate a blocker; encode it.
  • Any further avenue, idea, deferred consumer, "we should also…", scope the implementer chose not to expand into → file a follow-up task. An idea not in the tracker is lost.
  • Any stub / shortcut / known-imperfect choice → file it + reference the id in a code comment at the site (= Implementer-contract item 5).

A cycle that closes one task and files three precise follow-ups is a good cycle, not scope creep. The graph getting richer and more honest is the point.

Honest-failure discipline (the spine — do not compromise this)

Functionality-first changes WHERE rigor is applied, never WHETHER claims are true. Velocity comes from deferring polish, not from tolerating fake green.

  • "Done" requires every AC checked and the gate green — plus review GO on DEEP-gated tasks. Anything less stays In Progress with the truth written down.
  • Blocked > fake-complete. Re-triage to the precise root cause, file prerequisites with dependency edges, leave a note a future session can act on cold.
  • If a prior "Done" is found to rest on an overclaim (a comment that lies about the code, an unproven "robust", a flaky test sampled once as green): treat it as a defect of this work, fix it at root cause, and disclose it in the notes — do not re-game the AC text to match what was built and re-tick it.
  • Report measured numbers, not adjectives. "Tests pass" → the counts. "Not flaky" → ran N times, here are the results.

Failure modes & handling

  • Spawned implementer refuses to edit code (safety-reminder over-application on a benign repo): mitigations, in order — (a) lead the brief with explicit benign framing + concrete file pointers; (b) if it still refuses, the orchestrator implements that task directly in-thread. Review agents (read-only) are far less prone to this; the gate stays intact either way.
  • Context fatigue (very long sessions degrade reliability — the loop itself will eventually produce an overconfident error): the FIRST response is to delegate harder, not to stop — run the gate in a qa-test-runner subagent, the review in mped-architect, route fixes back to the implementer, so the orchestrator's own window stays small and the deep gates catch overconfidence in fresh contexts. Only once the orchestrator's own irreducible reasoning is degrading (and heavy work is genuinely already delegated) does "prefer a clean handoff over grinding" apply. Doing the gate/review/fix in your own window and then citing the resulting context load to stop is the self-inflicted anti-pattern (see Roles) — do not.
  • Subagent cycles are expensive: don't spawn one per trivial task; batch tightly-related small tasks into one brief, but never batch across a risky refactor boundary.

Backlog maturity / endgame (the loop doesn't just end — it hardens)

When the To-Do set nears zero, or every remaining task is environment- blocked / future-milestone scaffolding, do not declare victory and stop. A backlog reaching the bottom of its feature list is the signal to enlarge quality coverage — this wave is where the rigor deferred by the functionality-first doctrine actually happens, and it is only now that it pays: the surfaces have STABILIZED, so nothing hardened here is about to be rewritten. Seed it from the deferred-findings tasks step 4 filed all along, then enlarge. File and then work a new wave of tasks:

  • Review passes — end-to-end architecture review, cross-cutting consistency, dependency-graph sanity, dead-code/limitation audit.
  • Fuzzing & property tests — fuzz the input/parsing/serialisation boundaries; property/invariant tests for the core contracts (round-trips, idempotence, determinism, domain invariants).
  • Test-suite enlargement — negative tests, edge cases, the "prove the check bites" tests for every guard that currently only has a positive arm, regression pins for every fixed bug.
  • Documentation validation — docs/PRD/spec match the code; every documented invariant is actually asserted; examples in docs run; comments don't lie about the code (this exact defect class has been seen — make it a recurring audit task).

These are normal phase3-backlog-ralph tasks: same dependency-ordered selection, same implementer brief, same honest-stop discipline (a perfunctory "fuzz X" task filed only to keep the loop alive is itself an anti-pattern — hardening tasks must be real). Hardening-wave cycles run the DEEP gate by default — this wave is exactly where independent review earns its cost, because its findings land on code that will not move again.

Ordering vs Stop conditions (resolves the apparent conflict): the "remaining tasks are environment-blocked / future-milestone" stop does NOT fire the first time the feature list empties. First file and work the hardening wave. That stop applies only once the hardening wave is also genuinely exhausted, or context is thin (the other stop conditions still apply at any time). "Done with features" → "harden, fuzz, prove, document" → then stop honestly — not "finished" at the first empty feature list, and not "grind forever".

Stop conditions (choose honestly, don't grind)

Stop and give a status + recommendation when ANY of:

  • The next keystone is a deep/high-regression-risk refactor whose briefing or gate reconciliation would exceed the orchestrator's own remaining budget. NOTE: "warrants a fresh context" is normally satisfied by spawning a fresh implementer subagent for it — that is the fix, not a reason to stop. This stop fires only if even orchestrating it (writing the brief, reconciling reviewer verdicts) is beyond reach.
  • Remaining tasks are environment-blocked or future-milestone scaffolding and the Backlog-maturity hardening wave is also exhausted (this stop does not fire on the first empty feature list — see "Backlog maturity / endgame").
  • The review gate is repeatedly catching your own overconfidence (a reliability signal — stop, don't push).
  • The ORCHESTRATOR's OWN budget/context is thin enough that its irreducible reasoning would degrade — checked ONLY after gate/review/ fix are already delegated to subagents (a long window caused by doing that work yourself is not this condition; it is the self-inflicted anti-pattern — delegate it and continue).

A good stop = repo clean, every claim verified, next keystone precisely specified in the tracker, memory updated. A fresh session resumes cold with zero loss. Surface this as an explicit recommendation with options; do not silently stop and do not sycophantically pretend the whole backlog can be exhausted in one session.

Anti-patterns (never do these)

  • Shipping an IRREVERSIBLE-labeled task on the implementer's word alone (the deep gate exists precisely there) — and its mirror: running the deep gate on every ordinary feature cycle, which recreates the slow implement-while-hardening loop.
  • Hardening tentative surfaces: polishing wording, chasing edge cases, or deep-reviewing code that the current wave may still rewrite.
  • Cornerstone-avoidance: clearing easy hardening/follow-up tasks while an unblocked core/cornerstone task waits, because the cornerstone is hard, risky, or env-heavy. Core fundamentals come first (see step 0); "hard" is a cue to delegate the cornerstone to a fresh implementer, not to substitute safe busywork for it.
  • Blocking a feature cycle on non-gate-breaking findings instead of filing them for the hardening wave.
  • Sequential-by-ID task selection ignoring the dependency graph.
  • Rewriting an acceptance criterion to match what was built, then ticking it ("AC-gaming").
  • A workaround presented as a fix; a partial presented as complete.
  • Claiming green/robust/non-flaky from a single sample.
  • The orchestrator doing implementation, gate re-runs, review, or fixes in its OWN window (loading its context with build logs / diff reads), then invoking "context fatigue" to pause — the self-inflicted stop. Delegate the gate to qa-test-runner, the review to mped-architect, the fix back to the implementer; the orchestrator's window holds only compact verdicts. (Spawning a fresh implementer for deep work is the opposite of this anti-pattern — it is correct.)
  • Running the world-rebuilding BROAD suite on every re-verification pass — and its mirror: buying that time back by deleting coverage instead of persisting caches and setting a cadence.
  • Reporting "gate green" without naming which tier ran and what was skipped.
  • Writing a verification note for a run whose exit code was never captured, or keeping a note trail that records only the passes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.