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