From 8a560cc627687d8b683a8d54966a51b72a51ab08 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 5 Jul 2026 15:14:13 -0400 Subject: [PATCH] =?UTF-8?q?refactor(AGENTS.md):=20thin-index=20=C2=A7Sessi?= =?UTF-8?q?on-Learned=20Anti-Patterns=20to=20conductor/edit=5Fworkflow.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per agent_directives_consolidation_20260705 §3.1. The 5 items (ALWAYS use proper edit tool, decorator-orphan pitfall, ast.parse is not enough, git status trap, small edits beat big scripts) are now 1-line pointers to conductor/edit_workflow.md, which is the canonical home for edit-tool lessons-learned (per its §1, §6, §7). Net: 30 lines reduced to 7 lines (76% reduction in section size). Duplicate content removed; conductor/edit_workflow.md remains the canonical source for these rules. --- AGENTS.md | 33 ++++++--------------------------- 1 file changed, 6 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fef110fe..d41b4c54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,34 +86,13 @@ Rationale: the user is the only one who can authorize a new top-level namespace. ## Session-Learned Anti-Patterns (Added 2026-06-07) -These burned the most time in a recent startup_speedup session. The rules below are short because the rules above (and `conductor/edit_workflow.md`) are the source of truth. +The canonical home for edit-tool lessons-learned is `conductor/edit_workflow.md` (the 9 rules for `manual-slop_edit_file` etc.). This section is a thin pointer. -### 1. ALWAYS use the proper edit tool, not a custom script - -- For Python source edits, use `manual-slop_edit_file` with `old_string`/`new_string`. **Do NOT** write a standalone Python script that does file-level replacements. -- Custom scripts fail silently on: wrong indent in `new_content`, wrong EOL (CRLF vs LF) in `old_string` searches, wrong exact-string match (whitespace drift). -- When a script fails, debug the actual error message. Do not dismiss it and try a different approach. - -### 2. The decorator-orphan pitfall - -When inserting new methods **before an existing `@property` def**, your script will leave the `@property` decorator on the line above your new methods. The decorator then accidentally decorates YOUR new method (which is no longer a property, breaking any subsequent `@your_method.setter` calls). The file passes `ast.parse()` but blows up at import time. - -The fix: anchor on the **def line that has the `@property` ABOVE it**, and replace the pair `@property\n def foo(...)` with `@property\n def your_new(...)\n ...\n def foo(...)` — keeping the decorator attached to its original method. Or anchor on a different non-decorated landmark (e.g. `self._init_actions()`). - -### 3. `ast.parse()` "Syntax OK" is not enough - -`py_check_syntax` only confirms `ast.parse()` succeeds. Semantic errors (wrong decorator targets, wrong class attribute, missing `self`, etc.) are NOT caught. After any multi-line edit, ALWAYS: -- Import the module -- Instantiate the class -- Call the new method in the way it's expected to be called (e.g. `ctrl.foo_ts` vs `ctrl.foo_ts()` for properties vs methods) - -### 4. The "I'll just check git status" trap (now a HARD BAN, see Critical list above) - -If you suspect you might have lost work, the worst move is to run `git status` / `git restore` while a frantic user is watching. Pause, read the actual file, and admit what state you're in. The user knows their state better than you do. This trap has now caused irrecoverable data loss twice in one session — the ban is enforced above. - -### 5. Small, verified edits beat big scripts - -`conductor/edit_workflow.md` says it explicitly: 3-10 lines at a time, verify after each, repeat. If you find yourself writing a 200-line Python script to do an edit, you're doing it wrong. Use the MCP tools. +- **ALWAYS use the proper edit tool, not a custom script** — see `conductor/edit_workflow.md` §1. +- **The decorator-orphan pitfall** — see `conductor/edit_workflow.md` §6 (with the fix code). +- **`ast.parse()` "Syntax OK" is not enough** — see `conductor/edit_workflow.md` §7. +- **The "I'll just check git status" trap** — now a HARD BAN; see §"Critical Anti-Patterns" above. +- **Small, verified edits beat big scripts** — see `conductor/edit_workflow.md` §1. ---