Private
Public Access
0
0

docs(workflow): add Process Anti-Patterns section + Isolated-Pass rule

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.
This commit is contained in:
conductor-tier2
2026-06-09 14:03:00 -04:00
parent d7dc1e3b90
commit 631c40c9c4
+21
View File
@@ -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