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. ---