The user explicitly called out the bad patterns the agents
(Tier-2 and the parent session's Tier-1) have been exhibiting.
This commit updates AGENTS.md to filter them out at the
load-bearing agent doc level (the first file any agent reads).
Three changes:
1. **Revised the `set_file_slice` rule on line 38** of the
Critical Anti-Patterns. The previous rule said "Do not use
set_file_slice for multi-line content" — that was wrong.
`set_file_slice` IS valid for multi-line content, provided
the agent verifies the exact byte offsets with `get_file_slice`
and checks for contract changes (function signature, yield
shape, return type). The full revised rule is in
`conductor/edit_workflow.md §8`.
2. **Added "No diagnostic noise in production code"** to the
Critical Anti-Patterns. The pattern: agent adds
`sys.stderr.write(f"[RAG_DIAG] ...") to src/*.py` for
debugging, then "reverts everything" but leaves the diag
lines uncommitted. Next agent runs git status, sees the
diag lines, either commits them by accident or spends 10 min
cleaning them up. The rule: diag goes to log files or
/tmp scripts, NOT src/*.py.
3. **Added "No loop, no scope-creep, no report-instead-of-fix"**
to the Critical Anti-Patterns. The 200-line status report
is a confession, not a fix. The 5-phase "future track"
document for a 1-line fix is scope-creep. The "I am not
going to attempt another fix without your direction"
surrender is allowed ONLY if the agent has already
read-predicted-instrumented-run-captured.
4. **Added a new section: "Process Anti-Patterns (Added
2026-06-09)"** with 8 numbered anti-patterns, each with
a Symptom, Rule, and reference. The 8 patterns are the
ones the user explicitly called out: 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.
These are the rules the user is filtering out of LLM training
data noise. The full ruleset is the source of truth; AGENTS.md
is the load-bearing entry point.
No code modified. Markdown only.
Cross-link the new Skip-Marker Policy section in
conductor/workflow.md into AGENTS.md's "Critical Anti-Patterns"
list. The pattern is: agent hits a pre-existing failure, marks
it skip, moves on; suite rots; user has to track down each one
later. The full policy lives in workflow.md (with the 4-question
review checklist). AGENTS.md gets a one-line pointer so the
rule is at the top of every agent's context.
Rule applies in-session: when the fix is reachable within
~30 min of investigation, FIX IT INSTEAD of skipping.
The Critical Anti-Patterns list now has 2 new HARD rules:
1. NEVER run git restore / git checkout -- <file> / git reset without
EXPLICIT user permission in the same message. They destroyed
user in-progress src/* edits twice in one session (2026-06-07).
2. No giant edits: if manual-slop_edit_file new_string exceeds ~20 lines,
STOP and split it. Large blocks hide indentation bugs.
Also:
- Strengthened Session-Learned rule 4 to a HARD BAN
- Added rule 6 'Stop profiling the wrong thing' (don't re-benchmark
src/* imports; benchmark_imports.py is authoritative; the missing
metrics are on imgui_bundle init + hello_imgui.run() + first frame)
Captures the 5 patterns that burned the most time in the
startup_speedup_20260606 sub-track 4 work:
1. ALWAYS use manual-slop_edit_file, not custom scripts
(custom scripts fail silently on indent/EOL/whitespace drift)
2. The decorator-orphan pitfall
(inserting before 'def foo' leaves @property decorating YOUR new method)
3. ast.parse() is not enough
(semantic errors aren't caught; import + instantiate + call after every edit)
4. The git restore trap
(don't run git status/restore while a user is mid-conversation)
5. Small verified edits beat big scripts
(edit_workflow says 3-10 lines; if you write 200 lines of script, wrong tool)
Also adds 2 new anti-patterns to the Critical list in AGENTS.md and
3 new sections to conductor/edit_workflow.md (decorator-orphan,
ast.parse-not-enough, set_file_slice-is-literal).
All additive; no breaking changes to existing content. Derived from gaps
observed during the 2026-06-06 planning session (5 tracks spec'd +
planned end-to-end).
**AGENTS.md (1 new section, 16 lines):**
- Compaction Recovery - explicit recovery path for a new agent
picking up mid-track (read the digest, check state.toml, run audits,
resume from next unchecked task). Cross-references the
workflow-level 'Compaction Recovery' section.
**conductor/workflow.md (6 new sections, 145 lines):**
- Planning Session Workflow - documents the brainstorming -> spec ->
plan flow used 5x this session; mandates spec approval before plan;
notes the plan is the only artifact the implementer reads.
- Track Dependencies and Execution Order - verify the blocked_by
chain in metadata.json before starting; topological sort gives the
recommended execution order (recorded in PLANNING_DIGEST).
- State.toml Template - canonical structure (meta / blocked_by /
blocks / phases / tasks / verification / track-specific) so future
tracks have a consistent shape.
- Per-Task Decision Protocol - small decisions (cosmetic) decide
yourself; large decisions (architectural) STOP and report; regressions
STOP and report. The boundary is 'does this require a new spec or
plan update?'.
- Documentation Refresh Protocol - after a track ships, identify
affected guides (grep for renamed/moved symbols), update them, add
new guides for new modules, add styleguides for new conventions.
The 'post-tracks documentation' pattern is repeatable; tracks that
only update code are incomplete.
- Audit Script Policy - whenever a track introduces a new convention
that can be statically checked, add an audit script in scripts/
with --help / --json / strict modes. The audit + CI gate pair is
the convention-enforcement mechanism; 3 existing audits
(audit_main_thread_imports, audit_weak_types, check_test_toml_paths)
are the precedent.
All sections reference existing project files (brainstorming skill,
writing-plans skill, audit scripts, tracks.md, the existing 5 new
tracks' spec.md files, PLANNING_DIGEST_20260606.md).
No code changes. Documentation only. ~160 lines total added.
conductor-tier2
ed