From 631c40c9c42c044d6b6c8174392cbdd075bd7c84 Mon Sep 17 00:00:00 2001 From: conductor-tier2 Date: Tue, 9 Jun 2026 14:03:00 -0400 Subject: [PATCH] docs(workflow): add Process Anti-Patterns section + Isolated-Pass rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two additions to conductor/workflow.md §"Known Pitfalls": 1. **Isolated-Pass Verification Fallacy (Added 2026-06-09)** — the rule that a test passing in isolation but failing in batch is FAILING. The only verification that matters for live_gui tests is the batch run. This is the flip side of the existing "Live_gui Test Fragility (Authoring-Side)" rule. Cross-references that rule. 2. **Process Anti-Patterns (Added 2026-06-09)** — 8-rule summary list, with cross-reference to AGENTS.md for the full ruleset. The 8 patterns are: Deduction Loop, Report-Instead-of-Fix, Scope-Creep Track-Doc, Inherited-Cruft, Diagnostic Noise in Production, Premature Surrender, Verbose Commit Message, Isolated-Pass Verification Fallacy. Markdown only. No code modified. Cross-references AGENTS.md (the load-bearing agent doc) for the full text of each pattern. --- conductor/workflow.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/conductor/workflow.md b/conductor/workflow.md index 1635bfda..6243b0be 100644 --- a/conductor/workflow.md +++ b/conductor/workflow.md @@ -444,6 +444,27 @@ In particular, watch for: **Prevention:** When reorganizing a class body, run the AST check above immediately after the edit. This catches the issue in <1 second vs. finding it via failing live_gui tests minutes later. +### Isolated-Pass Verification Fallacy (Added 2026-06-09) + +A test that "passes when run after test X but fails in isolation" is a **fragile test, not a fragile fixture**. The flip side is also true: a test that "passes in isolation but fails in batch" is failing — its failure is masked by isolation. The only verification that matters for `live_gui` tests (or any test that depends on shared subprocess state) is the **batch run** in the suite the test will ship in. + +**Rule:** For any `live_gui` test or any test that depends on shared subprocess state, do NOT commit a fix that you have only verified in isolation. The fix must pass in the batched run that includes the tests that share the subprocess. Run the batch first. If the test fails in batch, your fix is incomplete. Per the existing `Live_gui Test Fragility (Authoring-Side)` rule above, the bisect requires both directions. If you only run in isolation, you cannot tell "test needs work" from "real app bug." + +### Process Anti-Patterns (Added 2026-06-09) + +These are the bad patterns the agents have been exhibiting that the user explicitly called out. The rules below are short. If you find yourself doing any of these, STOP and reread this section. + +For the full rationale on each, see `AGENTS.md` "Process Anti-Patterns." The summary rules: + +1. **The Deduction Loop (kill it).** You are allowed to run a failing test at most **2 times** in a single investigation. After the 2nd failure, STOP running the test. Read the code, predict the failure mode, instrument all relevant state in one pass, then run once more. If that fails, report to the user — do not loop. +2. **The Report-Instead-of-Fix Pattern (kill it).** A 200-line status report is a confession, not a fix. A good status report is 5-10 sentences. Status reports are allowed only when you have actually tried the fix and it failed with evidence, OR you are blocked on a decision the user must make. +3. **The Scope-Creep Track-Doc Pattern (kill it).** If the user asks for a fix, your output is the fix. A track doc is only appropriate when the fix is multi-day work. If the fix is < 100 lines, it does not get a track. If it would touch more than 5 files, it MIGHT get a track — but ask first. +4. **The Inherited-Cruft Pattern (kill it).** If the file is already broken from a previous session, the FIRST thing you do is ask the user: "this file is in a broken state from a previous agent. do you want me to (a) revert the working tree and start from a clean baseline, (b) finish the previous agent's intent, or (c) abandon the work entirely?" +5. **No Diagnostic Noise in Production (kill it).** Diag stderr goes to a log file or a /tmp script, not `src/*.py`. If you must add diag lines to production code, they are part of the same atomic commit as the fix — they do not live uncommitted in the working tree. +6. **The "I Am Not Going To Attempt Another Fix" Surrender (kill it).** This is correct ONLY if you have already done: read the source, predicted the failure, instrumented state, run once, captured full output. Otherwise you are surrendering too early. +7. **The Verbose-Commit-Message Pattern (kill it).** A commit message is 1-3 sentences. If it's longer than 15 lines, it's a report, not a commit message. Save the report for `docs/reports/`. +8. **The Isolated-Pass Verification Fallacy (kill it).** A test that passes in isolation but fails in batch is failing. Verify in batch, not isolation, for any test that touches shared subprocess state. + --- ## Planning Session Workflow