ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs(agents,edit_workflow): capture session-learned anti-patterns (2026-06-07)

Browse Source 
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).
This commit is contained in:
Edward R. Gonzalez
2026-06-06 22:52:02 -04:00
parent 229559caaa
commit 820cdab15a
2 changed files with 61 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/edit_workflow.md
+27
View File
@@ -38,6 +38,33 @@ Before ANY edit to a function you haven't touched recently:
- Nested blocks: ` ` (3 spaces total)
- NO 4-space indentation anywhere in this file
### 6. The Decorator-Orphan Pitfall (Added 2026-06-07)
When inserting new methods **before an existing `@property` def**:
```
@property
def perf_profiling_enabled(self) -> bool:
...
```
If you anchor on `def perf_profiling_enabled` and insert before it, the `@property` decorator on the line above is left orphaned on the line right before YOUR new method. Now `@property` decorates your method (which is no longer a property), and the original setter `@perf_profiling_enabled.setter` blows up at import with `'function' object has no attribute 'setter'`.
**Fix:** Anchor on a non-decorated landmark, or include the decorator in the replacement:
- `old_string` = ` self._init_actions()\n\n @property\n def perf_profiling_enabled`
- `new_string` = ` self._init_actions()\n\n def your_new(...)\n ...\n\n @property\n def perf_profiling_enabled`
This keeps the `@property` attached to its original method.
### 7. ast.parse() Is Not Enough (Added 2026-06-07)
`py_check_syntax` only confirms `ast.parse()` succeeds. Semantic errors (wrong decorator targets, wrong base class, wrong attribute, missing `self`) are NOT caught. After any multi-line edit, ALWAYS:
1. Import the module: `python -c "from src.app_controller import AppController"`
2. Instantiate the class
3. Call the new method in the way it's expected to be called (`ctrl.foo_ts` for a property, `ctrl.foo_ts()` for a method)
### 8. Do Not Use `set_file_slice` For Multi-Line Content (Added 2026-06-07)
`set_file_slice` does literal line replacement by design. It does not reindent, does not normalize EOL, does not parse decorators. Use it for surgical line-level edits (3-10 lines). If you need to insert or replace a multi-method block, use `manual-slop_edit_file` with verified exact-text old_string/new_string, or use `py_add_def` / `py_update_definition` for class/method-level work.
## Step-by-Step Workflow for gui_2.py
### Before ANY edit: