chore: interview before fixes and keep HANDOFF.md tiny

Require a short user interview before implementing bugs/features, and overwrite or clear HANDOFF.md so it never accumulates session history.

Co-authored-by: Cursor <cursoragent@cursor.com>

agents-docs/AGENT_WORKFLOW.md

@@ -17,50 +17,58 @@ Do **not** re-read this whole file every turn after the first skim.
 
 ## Workflow Orchestration
 
-### 1. Plan only when ambiguity is real
+### 1. Interview before implement (default)
 
-- Plan for unclear architecture or when the user asks.
-- Skip plan mode for focused, in-scope edits with clear acceptance criteria.
+- For bugs/features: short interview first (understanding, gaps, choices + recommended default, scope, proof) — then wait. See `/AGENTS.md` and `.cursor/rules/interview-before-fix.mdc`.
+- Do not guess past ambiguity; the user controls the implementation choices.
+- Skip only when the user opts out (“just fix it”) or an approved handoff already decided.
 
-### 2. Subagents sparingly
+### 2. Plan mode
+
+- Use plan mode when architecture is unclear or the user asks — the interview often replaces a heavy plan for normal bug fixes.
+- Skip long planning essays; prefer bullet choices.
+
+### 3. Subagents sparingly
 
 - Default: one agent.
 - Subagents only for true parallel search inside allowed paths.
 - Never spawn extra review agents unless the user asks.
 
-### 3. Handoff / short sessions
+### 4. Handoff / short sessions
 
 Triggers: user says handoff / new chat; thread is long with more major work left; switching objectives.
 
-Action: overwrite `agents-docs/HANDOFF.md` with `Status: active` (Goal, Completed, Changed files, Decisions, Failed approaches, Current issue, Next steps, Commands). Then stop major work and ask the user to open a new chat.
+Action: **overwrite** (never append) `agents-docs/HANDOFF.md` with `Status: active` and short sections. Then stop major work and ask the user to open a new chat.
 
-New chat: if handoff is active, read it first; continue Next steps; do not redo Completed work.
+New chat: if handoff is active, read it first; continue Next steps; do not redo Completed work. If Next steps still need choices, re-interview — don’t invent them.
 
-### 4. Self-Improvement Loop
+**When finished:** clear `HANDOFF.md` to `Status: none` with empty sections so the file stays tiny for the next session.
+
+### 5. Self-Improvement Loop
 
 **At session start:** `LESSONS-INDEX.md` only; open matching lesson bodies by tag.
 
 Record a lesson + index line when corrected. Prefer fewer sharp rules (~20).
 
-### 5. CONTEXT.md upkeep
+### 6. CONTEXT.md upkeep
 
 Default: `toju-app/CONTEXT.md`. Read `electron/CONTEXT.md` only when touching Electron. Other packages only when in scope.
 
-### 6. ADR upkeep
+### 7. ADR upkeep
 
 Only when hard-to-reverse + surprising + real trade-offs. Contract: `agents-docs/AGENTS_ADRS.md`.
 
-### 7. Verification Before Done (behavior first)
+### 8. Verification Before Done (behavior first)
 
-Done = asked functionality works. Unit green ≠ done for product asks. Prefer in-scope proof; don’t pull e2e/server “just to be sure.”
+Done = asked functionality works **as the user confirmed in the interview**. Unit green ≠ done for product asks.
 
-### 8. Demand Elegance (Balanced)
+### 9. Demand Elegance (Balanced)
 
-One pause for non-trivial design; skip for obvious fixes.
+One pause for non-trivial design; skip for obvious fixes once the user has chosen a direction.
 
-### 9. Autonomous Bug Fixing
+### 10. Bug fixing (after interview)
 
-Fix with evidence in default scope. If root cause is clearly `server/` (or similar), say so and ask to expand scope.
+Implement the approved plan with evidence in default scope. If root cause is clearly outside scope, say so and ask to expand — don’t silently crawl.
 
 ---
 
@@ -72,4 +80,4 @@ Gitea: `git.azaaxin.com/myxelium/Toju`. Branch `<type>/<short-description>`; PR
 
 ## Core Principles
 
-- **Simplicity First** · **No Laziness** · **Minimal Impact** · **Cheap Context** · **Default Scope Fence** · **Handoff Beats Fat Context**
+- **Simplicity First** · **No Laziness** · **Minimal Impact** · **Cheap Context** · **Default Scope Fence** · **Handoff Beats Fat Context** · **Interview Before Guessing**

agents-docs/BUG_TRACKER.md

@@ -14,11 +14,12 @@ When the user says e.g. `fix bug "Images and files in chat doesn't load"`:
 
 1. **Resolve one note** under `Log/Bugs/` whose title matches (usually `Bug - <title>.md`). Do not list or read the whole inbox.
 2. **Read that note** (Description, Steps, Expected/Actual, Logs). Read attachments only under that bug’s attachment folder if referenced.
-3. Acceptance criteria = the note’s Expected Result (plus any clarifying line from the user).
-4. **Fix in default repo scope** (`toju-app/` + targeted `electron/` + CI) per `AGENTS.md`. Do not crawl `server/` / `e2e/` / other packages unless the note or user clearly requires it — then ask once.
-5. Prove the asked behavior (not only unit-green). Prefer a regression that encodes the note’s failure mode.
-6. When done: set that note’s frontmatter `status` to `Resolved` (or `Closed` if the user prefers). Do not rewrite Description / Investigation / Resolution unless asked.
-7. Long thread + more work left → write `agents-docs/HANDOFF.md` and ask for a new chat.
+3. **Interview before implement** (see `/AGENTS.md` and `.cursor/rules/interview-before-fix.mdc`): restate the bug, list gaps, present choices with a recommended default, propose scope and proof of done — then **wait** for the user. Do not start coding until they answer (unless they said “just fix it”).
+4. Acceptance criteria = the note’s Expected Result **plus** the user’s interview answers.
+5. **Fix in default repo scope** (`toju-app/` + targeted `electron/` + CI) per `AGENTS.md`. Do not crawl `server/` / `e2e/` / other packages unless the note or user clearly requires it — then ask once.
+6. Prove the asked behavior (not only unit-green). Prefer a regression that encodes the note’s failure mode.
+7. When done: set that note’s frontmatter `status` to `Resolved` (or `Closed` if the user prefers). Do not rewrite Description / Investigation / Resolution unless asked.
+8. Long thread + more work left → write `agents-docs/HANDOFF.md` and ask for a new chat.
 
 Do **not** re-read `BUG_TRACKER.md` every turn after the first use. Do **not** load the stale “open bugs” snapshot as truth — the vault files are source of truth.
 

agents-docs/HANDOFF.md

@@ -1,13 +1,13 @@
 # Session Handoff
 
-> **New chat:** attach `@agents-docs/HANDOFF.md` (and only the files listed under Changed files). Say: continue from this handoff; do not redo completed work. Stay in default scope unless Next steps expand it.
+> **New chat:** attach `@agents-docs/HANDOFF.md` (and only files under Changed files). Say: continue from this handoff; do not redo completed work.
 >
-> **Agents cannot open a new chat** — write/update this file, then ask the user to start one.
+> **Agents cannot open a new chat** — overwrite this file, then ask the user to start one.
+>
+> **Keep this file tiny:** always **overwrite** the whole file (never append). When the task is finished, **clear** back to `Status: none` and empty sections (see below).
 
 **Status:** none
 
-<!-- When Status is `active`, fill every section below. When done with a handoff cycle, set Status back to `none` or overwrite on the next handoff. -->
-
 ## Goal
 
 ## Completed

agents-docs/LESSONS-INDEX.md

@@ -53,7 +53,8 @@ Tags help grepping: `rg '\\[attachments\\]' agents-docs/LESSONS-INDEX.md`
 - Use blob URLs for inline attachment previews — `[attachments] [electron]`
 - Resolve Electron drag-and-drop file paths with webUtils — `[attachments] [electron]`
 - Preserve uploader local attachment paths across sync — `[attachments] [persistence]`
+- Interview before coding; don’t guess the fix — `[workflow] [bugs] [tokens]`
 - Prove the asked behavior; unit-green is not done — `[verification] [testing] [workflow]`
 - Default to `toju-app/` + targeted `electron/` + CI; do not crawl the monorepo — `[workflow] [tokens] [scope]`
-- Write HANDOFF.md and ask the user for a new chat — agents cannot open chats — `[workflow] [tokens] [handoff]`
+- Write/overwrite HANDOFF.md for new chats; clear it when the task finishes — `[workflow] [tokens] [handoff]`
 

agents-docs/LESSONS.md

@@ -25,6 +25,13 @@ Durable rules for AI agents working on this project.
 
 ## Lessons
 
+### Interview before coding; don’t guess the fix [workflow] [bugs] [tokens]
+
+- **Trigger:** about to edit product code for a bug/feature after reading the ask or Obsidian note, while acceptance, approach, or scope is still ambiguous or has real alternatives.
+- **Rule:** send a short interview (understanding, gaps, A/B/C + recommended default, proposed scope, proof of done), wait for the user’s choices, then implement only that — skip only if they said “just fix it” / “no interview.”
+- **Why:** unprompted guesses cause wrong fixes and expensive back-and-forth; one clarifying turn costs less than a wrong implementation thread.
+- **Example:** `fix bug "Images and files in chat doesn't load"` → read the note → ask whether the failure is channel-switch blank vs cold reload vs both before touching attachment services.
+
 ### Default to `toju-app/` + targeted `electron/` + CI; do not crawl the monorepo [workflow] [tokens] [scope]
 
 - **Trigger:** about to browse all of `electron/`, or to `grep`/`Read` under `server/`, `e2e/`, `website/`, or `docs-site/` on a normal product bug without the user naming those packages.
@@ -35,9 +42,9 @@ Durable rules for AI agents working on this project.
 ### Write HANDOFF.md and ask the user for a new chat — agents cannot open chats [workflow] [tokens] [handoff]
 
 - **Trigger:** the thread is long, the user says "handoff"/"new chat", or a new major objective starts while more work remains.
-- **Rule:** overwrite `agents-docs/HANDOFF.md` with `Status: active` and the eight sections, then ask the user to start a new chat attaching that file; never pretend you opened a fresh chat.
-- **Why:** fat chat history dominates token burn on problem-solving models; a 5–10k handoff replaces 100k+ of mixed failure/tool output.
-- **Example:** user: "handoff" → write HANDOFF → reply: "Start a new chat and attach `@agents-docs/HANDOFF.md`; say continue from handoff."
+- **Rule:** **overwrite** (never append) `agents-docs/HANDOFF.md` with `Status: active` and short sections, ask the user to start a new chat with that file; when the handoff task is finished, **clear** the file to `Status: none` with empty sections.
+- **Why:** fat chat history dominates token burn; an appending handoff file becomes a second fat archive that every new chat reloads.
+- **Example:** user: "handoff" → replace HANDOFF → reply: "Start a new chat and attach `@agents-docs/HANDOFF.md`." Later when done → reset HANDOFF to empty `Status: none`.
 
 ### Prove the asked behavior; unit-green is not done [verification] [testing] [workflow]