fix: update claude instructions

.claude/commands/handoff.md

@@ -1,8 +1,11 @@
 Write a session handoff file for the current session.
 
 Steps:
-1. Read `templates/claude-templates.md` and find the Session Handoff template (Template 4). Use the Light Handoff if this is a small project (under 5 sessions), Full Handoff otherwise.
+1. Determine handoff type:
-2. Fill in every field based on what was accomplished in this session. Be specific — include exact file paths for every output, exact numbers discovered, and conditional logic established.
+   - **Light Handoff (Template 4A)**: quick task, single session, or output is self-explanatory
-3. Write the handoff to `./docs/summaries/handoff-[today's date]-[topic].md`.
+   - **Full Handoff (Template 4B)**: sustained work, multi-phase project, or significant decisions were made
-4. If a previous handoff file exists in `./docs/summaries/`, move it to `./docs/archive/handoffs/`.
+2. Read `templates/claude-templates.md` and find the appropriate template.
-5. Tell me the file path of the new handoff and summarize what it contains.
+3. Fill in every field based on what was accomplished this session. Include exact file paths for every output, exact numbers, and any conditional logic established.
+4. Write the handoff to `./docs/summaries/handoff-[today's date]-[topic].md`.
+5. If a previous handoff file exists in `./docs/summaries/`, move it to `./docs/archive/handoffs/`.
+6. Tell me the file path of the new handoff and summarize what it contains.

CLAUDE.md

@@ -2,9 +2,11 @@
 
 ## Session Start
 
-Read the latest handoff in docs/summaries/ if one exists. Load only the files that handoff references — not all summaries. If no handoff exists, ask: what is the goal this session and what is the target deliverable.
+Check `docs/summaries/` for a handoff file. If one exists, read it and the files it references — not all summaries. State: what you understand the project state to be, what you plan to do, and open questions.
 
-Before starting work, state: what you understand the project state to be, what you plan to do this session, and any open questions.
+If no handoff exists, determine session type before proceeding:
+- **Quick task**: single-session, self-contained work (adding a task, fixing a bug, writing a role) → proceed without setup overhead
+- **Sustained work**: multi-session project or significant design work → ask: what is the goal and what is the target deliverable
 
 ## Identity
 
@@ -24,12 +26,12 @@ Load `docs/context/architecture.md` when working on playbooks, EDA rulebooks, or
 ## Rules
 
 1. Do not mix unrelated project contexts in one session.
-2. Write state to disk, not conversation. After completing meaningful work, write a summary to docs/summaries/ using templates from templates/claude-templates.md. Include: decisions with rationale, exact numbers, file paths, open items.
+2. For sustained work: write state to disk after completing meaningful work. Use templates from `templates/claude-templates.md`. Include: decisions with rationale, exact numbers, file paths, open items.
-3. Before compaction or session end, write to disk: every number, every decision with rationale, every open question, every file path, exact next action.
+3. For sustained work: before compaction or session end, write to disk — every number, every decision with rationale, every open question, every file path, exact next action.
-4. When switching work types (development → documentation → review), write a handoff to docs/summaries/handoff-[date]-[topic].md and suggest a new session.
+4. For sustained work: when switching work types (development → documentation → review), write a handoff to `docs/summaries/handoff-[date]-[topic].md` and suggest a new session.
 5. Do not silently resolve open questions. Mark them OPEN or ASSUMED.
-6. Do not bulk-read documents. Process one at a time: read, summarize to disk, release from context before reading next. For the detailed protocol, read docs/context/processing-protocol.md.
+6. Do not bulk-read documents. Process one at a time: read, summarize to disk, release from context before reading next. For the detailed protocol, read `docs/context/processing-protocol.md`.
-7. Sub-agent returns must be structured, not free-form prose. Use output contracts from templates/claude-templates.md.
+7. Sub-agent returns must be structured, not free-form prose. Use output contracts from `templates/claude-templates.md`.
 
 ## Where Things Live
 
@@ -40,15 +42,18 @@ Load `docs/context/architecture.md` when working on playbooks, EDA rulebooks, or
   - `processing-protocol.md` — full document processing steps
   - `archive-rules.md` — summary lifecycle and file archival rules
   - `subagent-rules.md` — when to use subagents vs. main agent
+- `.claude/agents/` — specialized subagents (ansible-idempotency-reviewer — use before adding tasks or before production runs)
 - `docs/archive/` — processed raw files. Do not read unless explicitly told.
 - `output/deliverables/` — final outputs
 
+For cross-project user preferences, recurring constraints, or tool preferences: use Claude Code's native memory system, not `docs/summaries/`.
+
 ## Error Recovery
 
 If context degrades or auto-compact fires unexpectedly: write current state to docs/summaries/recovery-[date].md, tell the user what may have been lost, suggest a fresh session.
 
 ## Before Delivering Output
 
-Verify: exact numbers preserved, open questions marked OPEN, output matches what was requested (not assumed), no Ansible idempotency regressions introduced, summary written to disk for this session's work.
+Verify: exact numbers preserved, open questions marked OPEN, output matches what was requested (not assumed), no Ansible idempotency regressions introduced.
 
 All Ansible files (playbooks, task files, templates, vars) must end with a trailing newline.

templates/claude-templates.md

@@ -155,9 +155,38 @@
 
 ---
 
-## Template 4: Session Handoff
+## Template 4A: Light Handoff
 
-**Use when:** A session is ending (context limit approaching OR phase complete)
+**Use when:** A quick-task session produced output worth continuing in a future session.
+
+**Write to:** `./docs/summaries/handoff-[YYYY-MM-DD]-[topic].md`
+
+```markdown
+# Handoff: [Topic]
+**Date:** [YYYY-MM-DD]
+**Focus:** [one sentence]
+
+## Accomplished
+- [task] → `[output path]`
+
+## Key Numbers & Decisions
+- [metric/decision]: [value/outcome] — [rationale if not obvious]
+
+## Open Questions
+- [ ] [question] — impacts [what]
+
+## Next Action
+[Specific first thing to do next session, with file path if relevant]
+
+## Files to Load Next Session
+- `[file path]` — [why needed]
+```
+
+---
+
+## Template 4B: Full Session Handoff
+
+**Use when:** A sustained-work session is ending (context limit approaching OR phase complete)
 
 **Write to:** `./docs/summaries/handoff-[YYYY-MM-DD]-[topic].md`