diff --git a/conductor/directives/deduction_loop_limit/v1.md b/conductor/directives/deduction_loop_limit/v1.md new file mode 100644 index 00000000..0f720788 --- /dev/null +++ b/conductor/directives/deduction_loop_limit/v1.md @@ -0,0 +1,16 @@ +# deduction_loop_limit — v1 + +**Why this iteration:** Lifted verbatim from `AGENTS.md` §"Process Anti-Patterns" #1 (lines 119-125). This is the baseline encoding — the symptom-rule-pair style currently in production. +Future variants will test alternative encodings (rule-only, tabular) against this baseline. + +**Source:** `AGENTS.md:119-125` + +--- + +### 1. The Deduction Loop (kill 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. \ No newline at end of file diff --git a/conductor/directives/inherited_cruft_ask_first/v1.md b/conductor/directives/inherited_cruft_ask_first/v1.md new file mode 100644 index 00000000..f695654f --- /dev/null +++ b/conductor/directives/inherited_cruft_ask_first/v1.md @@ -0,0 +1,14 @@ +# inherited_cruft_ask_first — v1 + +**Why this iteration:** Lifted verbatim from `AGENTS.md` §"Process Anti-Patterns" #4 (lines 146-150). This is the baseline encoding — the symptom-rule-pair style currently in production. +Future variants will test alternative encodings (rule-only, tabular) against this baseline. + +**Source:** `AGENTS.md:146-150` + +--- + +### 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. \ No newline at end of file diff --git a/conductor/directives/no_skip_markers_as_avoidance/v1.md b/conductor/directives/no_skip_markers_as_avoidance/v1.md new file mode 100644 index 00000000..75a3086f --- /dev/null +++ b/conductor/directives/no_skip_markers_as_avoidance/v1.md @@ -0,0 +1,32 @@ +# no_skip_markers_as_avoidance — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Skip-Marker Policy" (lines 777-790) + `AGENTS.md` "Critical Anti-Patterns" (line 54). This is the baseline encoding — the rule-plus-allowed/not-allowed-lists style currently in production. +Future variants will test alternative encodings (rule-only, tabular) against this baseline. + +**Source:** `conductor/workflow.md:777-790 + AGENTS.md:54` + +--- + +## Skip-Marker Policy: Documentation, Not Avoidance + +`@pytest.mark.skip(reason=...)` is **documentation of a known failure**, not a way to avoid fixing the underlying bug. Skip markers are useful for: + +- **Opt-in integration tests** that require external resources (a real API key, a live provider, a specific env var). Use `@pytest.mark.skipif(...)` with an env-var gate so the test runs when the resource is available and skips by default. +- **Tests for features that don't exist yet** (planned but not implemented). +- **Tests for features behind a feature flag** that's currently off. + +Skip markers are NOT useful for: + +- **Pre-existing failing tests** (a test that "used to pass" or "was supposed to pass but the underlying code regressed"). The underlying code/test should be fixed in-session. +- **Tests that the agent doesn't understand** ("I don't know how to fix this, so I'll skip it"). Escalate to a Tier 4 QA agent for analysis, or ask the user. +- **Tests with racy assertions that the agent doesn't want to debug** (e.g., a `time.sleep(0.5)` would fix it). Fix the race, don't skip. + +**When you add a skip marker, you MUST also:** +1. Document the underlying issue in the `reason=` string (one or two sentences). +2. State what the fix would be (file:line or a one-line description). +3. Commit the skip with a follow-up note in the commit body that records the underlying issue, so the next agent (or future self after compaction) can find it via `git log --oneline --grep "skip"`. + +--- + +From `AGENTS.md` "Critical Anti-Patterns": +- Do not use `@pytest.mark.skip` as an excuse to AVOID fixing the underlying bug. Skip markers are documentation of known failures; the failure must be addressed with priority in-session when feasible. See `conductor/workflow.md` "Skip-Marker Policy" for the full policy and review checklist. \ No newline at end of file diff --git a/conductor/directives/report_instead_of_fix_ban/v1.md b/conductor/directives/report_instead_of_fix_ban/v1.md new file mode 100644 index 00000000..d6e94601 --- /dev/null +++ b/conductor/directives/report_instead_of_fix_ban/v1.md @@ -0,0 +1,23 @@ +# report_instead_of_fix_ban — v1 + +**Why this iteration:** Lifted verbatim from `AGENTS.md` §"Process Anti-Patterns" #2 (lines 127-137). This is the baseline encoding — the symptom-rule-pair style currently in production. +Future variants will test alternative encodings (rule-only, tabular) against this baseline. + +**Source:** `AGENTS.md:127-137` + +--- + +### 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. \ No newline at end of file diff --git a/conductor/directives/scope_creep_track_doc_ban/v1.md b/conductor/directives/scope_creep_track_doc_ban/v1.md new file mode 100644 index 00000000..78776d58 --- /dev/null +++ b/conductor/directives/scope_creep_track_doc_ban/v1.md @@ -0,0 +1,14 @@ +# scope_creep_track_doc_ban — v1 + +**Why this iteration:** Lifted verbatim from `AGENTS.md` §"Process Anti-Patterns" #3 (lines 139-144). This is the baseline encoding — the symptom-rule-pair style currently in production. +Future variants will test alternative encodings (rule-only, tabular) against this baseline. + +**Source:** `AGENTS.md:139-144` + +--- + +### 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. \ No newline at end of file diff --git a/conductor/directives/verbose_commit_message_ban/v1.md b/conductor/directives/verbose_commit_message_ban/v1.md new file mode 100644 index 00000000..f3354a39 --- /dev/null +++ b/conductor/directives/verbose_commit_message_ban/v1.md @@ -0,0 +1,14 @@ +# verbose_commit_message_ban — v1 + +**Why this iteration:** Lifted verbatim from `AGENTS.md` §"Process Anti-Patterns" #7 (lines 170-173). This is the baseline encoding — the symptom-rule-pair style currently in production. +Future variants will test alternative encodings (rule-only, tabular) against this baseline. + +**Source:** `AGENTS.md:170-173` + +--- + +### 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/`. \ No newline at end of file