Private
Public Access
0
0

refactor(conductor/workflow.md): promote §Process Anti-Patterns to canonical home

Per agent_directives_consolidation_20260705 §3.2.

The 14-line abridged §Process Anti-Patterns section (1-line summaries per
pattern) is promoted to the full canonical home: each of the 8 anti-patterns
now has the full Symptom + Rule content matching what was previously in
AGENTS.md. The 9th item (Workspace-Path Drift Pattern) was already
present here and is preserved.

AGENTS.md §Process Anti-Patterns is now a thin index pointing here
(per the previous commit in Phase 1.3). The canonical home for the full
process anti-pattern content is now conductor/workflow.md.

Net: 14 lines expanded to 80 lines (canonical expansion). 9 items
with full Symptom + Rule content. The 8 anti-patterns are now
locally accessible from the operational workflow file where they're
most actionable.
This commit is contained in:
2026-07-05 15:17:07 -04:00
parent e9ae8cc459
commit fa0ba73035
+70 -12
View File
@@ -512,21 +512,79 @@ A test that "passes when run after test X but fails in isolation" is a **fragile
**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)
### Process Anti-Patterns (Added 2026-06-09) — canonical home
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.
These are the bad patterns the agents have been exhibiting that the user explicitly called out as dog-shit. The rules below are short. If you find yourself doing any of these, STOP and reread this section. AGENTS.md §"Process Anti-Patterns" is a thin index that points here.
For the full rationale on each, see `AGENTS.md` "Process Anti-Patterns." The summary rules:
#### 1. The Deduction Loop (kill it)
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.
9. **The Workspace-Path Drift Pattern (kill it, added 2026-06-09).** Test workspaces live in the project tree under `tests/artifacts/`. Conftest creates them. **Never** use `tmp_path_factory.mktemp` for test infrastructure workspaces (it lives in `%TEMP%` and the user cannot find it). **Never** use env vars for test paths (hidden global state). **Never** add CLI args for test paths (conftest is the right place). The pattern: module-level constant in conftest that computes `Path(f"tests/artifacts/<workspace>_<timestamp>")` at import time. See `conductor/code_styleguides/workspace_paths.md` for the full rule and the 4-day agent churn that led to it.
**Symptom:** Run test → fail → read log → form hypothesis → run again → fail differently → add diag → run again → fail again → loop. You end up running the same test 4+ times in one session, each run reading partial log output.
**Rule:** 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 relevant source code (`get_file_slice` or `py_get_skeleton`), predict the failure mode from the code, and instrument ALL the relevant state in one pass before the next run. If the test still fails after 1 instrumented run, report to the user — do not loop.
**Worst case captured upfront.** Before running the test, ask: "what is the worst-case information I will need if this fails?" Add the diag for that, then run. The diag lines themselves are wasteful in production — see "No Diagnostic Noise in Production" below.
#### 2. The Report-Instead-of-Fix Pattern (kill it)
**Symptom:** You can't fix the bug. You write a 200-line status report explaining why you can't fix it. The report contains "What I tried this session", "What I am NOT going to do", "What you can do", and "Files changed in this session (cumulative)." The report is a confession, not a fix.
**Rule:** A status report is 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.
A status report is NOT allowed when:
- You are avoiding a hard problem by writing prose about it.
- The user asked for a fix and you have not yet tried.
- The "what you can do" section is a list of options to defer to the user instead of picking the best one and doing it.
A good status report is 5-10 sentences, not 200 lines.
#### 3. The Scope-Creep Track-Doc Pattern (kill it)
**Symptom:** The user asks for a 1-line fix. You write a 5-phase "future track" spec with 140 lines of scope, audit findings, recommendations, and "out of scope" sections. The track doc is now larger than the fix it was meant to scope.
**Rule:** 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 that requires a plan. If the fix is < 100 lines, it does not get a track. If the fix would touch more than 5 files, it MIGHT get a track — but ask first.
#### 4. The Inherited-Cruft Pattern (kill it)
**Symptom:** The previous agent left a half-finished refactor in the working tree. The file is broken. You try to fix it and make it worse. You try again. You make it worse. The file stays broken for 3 days.
**Rule:** If the file is already in a broken state 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?" You do not start by "trying to fix" the broken file. The user's answer determines the work, not your assumption.
#### 5. No Diagnostic Noise in Production (kill it)
**Symptom:** You add `sys.stderr.write(f"[RAG_DIAG] ...)")` to `src/rag_engine.py` and `src/app_controller.py` to debug a test failure. The diag lines help. You "revert everything" but leave the 4-8 diag lines in the working tree uncommitted. The next agent runs `git status`, sees the diag lines, and either commits them by accident or spends 10 minutes cleaning them up.
**Rule:** Diagnostic stderr goes to a log file (`tests/artifacts/<test_name>.diag.log`) or to a temporary diagnostic script (`/tmp/diag_rag.py`), NOT to `src/*.py`. If you absolutely must instrument a production function for a single test run, the diag lines are part of the same atomic commit as the fix — they do not live uncommitted in the working tree. If you "revert everything," that means the diag lines are also reverted.
#### 6. The "I Am Not Going To Attempt Another Fix Without Your Direction" Surrender (kill it)
**Symptom:** You've tried 3 things. None worked. You write: "I am not going to attempt another fix without your direction." Then you wait for the user to tell you what to do.
**Rule:** This is correct ONLY if you have already done the things below:
- Read the actual source code, not from memory
- Predicted the failure mode from the code
- Instrumented the relevant state in one pass
- Run the test once with instrumentation
- Captured the full output, not partial output
If you have done all 5 and are still stuck, surrendering is fine. If you have not, you are surrendering too early. The user does not want to be your strategist; the user wants the agent to make progress.
#### 7. The Verbose-Commit-Message Pattern (kill it)
**Symptom:** Your commit message is 50 lines. It contains the root cause analysis, the alternatives you considered, the side effects you considered, the cross-references, the "what this doesn't fix", the "what to verify", and a personal essay. The commit message is longer than the diff it describes.
**Rule:** A commit message is a 1-3 sentence summary. The body is for non-obvious "why" details, not for re-stating what the diff shows. If your commit message is longer than 15 lines, you are writing a report, not a commit message. Save the report for `docs/reports/`.
#### 8. The "Isolated Pass" Verification Fallacy (kill it)
**Symptom:** You run the test in isolation. It passes. You commit. The test fails in batch. You didn't notice because you never ran the batch.
**Rule:** For any `live_gui` test or any test that depends on shared subprocess state, the **only verification that matters is the batch run**. A test that passes in isolation but fails in batch is failing — it's just that the failure is masked by isolation. Per the existing `Live_gui Test Fragility` rule: "Bisect failures by running the test both in the full suite and in isolation to distinguish 'test needs work' from 'real app bug'." If you only ever run in isolation, you cannot tell the difference.
#### 9. The Workspace-Path Drift Pattern (kill it, added 2026-06-09)
Test workspaces live in the project tree under `tests/artifacts/`. Conftest creates them. **Never** use `tmp_path_factory.mktemp` for test infrastructure workspaces (it lives in `%TEMP%` and the user cannot find it). **Never** use env vars for test paths (hidden global state). **Never** add CLI args for test paths (conftest is the right place). The pattern: module-level constant in conftest that computes `Path(f"tests/artifacts/<workspace>_<timestamp>")` at import time. See `conductor/code_styleguides/workspace_paths.md` for the full rule and the 4-day agent churn that led to it.
---
## Planning Session Workflow