docs(context): require fresh implementation sessions

This commit is contained in:
zap
2026-03-12 19:43:17 +00:00
parent 06fa5821a5
commit 0fe5cd52d9
5 changed files with 125 additions and 5 deletions

View File

@@ -165,6 +165,29 @@ Before suggesting setup, re-setup, or asking the user for configuration details,
If something is already configured, frame the next step as validation, debugging, or operations — not fresh setup.
### Fresh-session implementation discipline
For non-trivial implementation work, prefer a fresh isolated session/run instead of piling more execution onto a long main-session context window.
Default pattern:
1. use the current session to clarify scope, inspect state, and decide the plan
2. write or refresh a compact state file (`WIP.md` for the standing plan, plus `HANDOFF.md` for the immediate baton-pass when useful)
3. start a fresh isolated implementation session/run
4. have that fresh session execute the plan from the state files rather than inheriting a bloated chat history
Context-window rule of thumb:
- keep the main session for direction, approvals, and summaries
- keep implementation sessions lean and execution-focused
- prefer file-based continuity over dragging long conversational context forward
Handoff rule:
- before ending, compaction, or spawning a fresh implementation session, leave a concise next-session handoff with:
- current goal
- exact next actions
- blockers / open questions
- relevant files / ids / commands
- what counts as success for the next pass
## ACP Claude model-tier routing
When delegating work to Claude via ACP (`runtime: "acp"`, `agentId: "claude"`), pick model tier by complexity/risk: