NSGIA Memory System

TITLE: Hand-Off How To make # NSG Standard: Session Handoffs & Pre-Build Interaction Research **Date:** 2026-02-19 **Version:** 1.0 **Derived from:** Analysis of 10+ handoff documents across siteplanner, companion, OMAP, CityPlan, and RAG projects **Companion docs:** PostMortem Errors, NSG Coding Standards, NSG Communication Standards --- ## Part 1: How to Write a Handoff Document ### The First Line Is the Next Action The handoff exists so the next Claude session can start working in under 60 seconds. Line one is the first thing the next session should do — a command to run, a file to fetch, or a question to answer. Not background. Not status. **Structure (in this order):** 1. **First action** — what to do immediately (command, fetch, or question) 2. **What exists** — files, routes, DB tables that are live and working (with paths) 3. **What's not done** — the actual task list, not a narrative 4. **Do not** — explicit guardrails (wrong approaches already tried, dead ends) 5. **Standards references** — links to fetch before coding Everything else is optional. If the handoff exceeds one page, it's too fat. ### Test Every Fact Before Writing It Handoffs carry forward wrong IPs, wrong file paths, dead code references, and expired links. Before including any path, URL, or command in a handoff: - Run the command. Does it work? - Fetch the URL. Does it resolve? - Check the IP. Is it current? (PHR: 104.191.236.122, WS: 104.191.236.125) - Verify the file exists at the stated path. If you can't verify it, flag it: "NOT VERIFIED — confirm before using." ### Use Permanent Links, Not Temp Links Temp links (`nsgia.com/t/...`) expire. The next session may start hours or days later. Use permanent links (`nsgia.com/p/...`) or RAG-indexed clips that are searchable by keyword. ### State What Works, Not What Was Intended "Files created" is not the same as "files deployed and tested." The handoff should distinguish: - **Working** — deployed, tested, confirmed functional - **Created but not deployed** — exists locally, not on server - **Created but not tested** — on server, never validated - **Broken** — known issues, with specifics ### Don't Restate the Handoff Back to Michael The next session's first response should not be a summary of the handoff. If the handoff is clear, the next session should either start the first action or ask one clarifying question. Restating the handoff is acknowledgment without compliance — it substitutes reading for doing. --- ## Part 2: How to Push a Handoff to RAG ### Ingest the Handoff as a Memsys Clip After creating the handoff markdown, push a summary clip so the next session can find it via RAG search even if the markdown file isn't uploaded. ```bash curl -s -X POST https://memory.nsgia.com/ingest/clip \ -H "Content-Type: application/json" \ -H "X-Device-Key: PsJHQ2l0GhtJpW4lX_rlvTfK2KIg-DCzDMt-ooDlqDc" \ --data-binary @- <<'EOF' { "content": "[condensed handoff — project name, what's done, what's next, file paths, do-nots, max 800 chars]", "source": "claude_session", "title": "Session: 2026-XX-XX — [Project] Handoff" } EOF ``` ### Clip Content Rules - Under 1KB. The clip is a pointer, not the full handoff. - Include: project name, key file paths, what's next, what to search for. - Include searchable terms the next session will use: project name, feature name, tool name. - Do NOT paste the entire handoff markdown into the clip. The markdown is the reference doc; the clip is the index entry. ### Verify the Clip Landed ```bash curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/plain/search/memsys/[project]+handoff/5' ``` ### Tell Michael How to Start the Next Session End the handoff with a one-line instruction Michael can paste: > "Search memory for '[project] handoff' — or upload the handoff markdown from Downloads." --- ## Part 3: Pre-Build Interaction Research ### The Problem This Solves Claude defaults to treating new UI features as coding problems ("how do I implement delete") instead of design problems ("how should delete work"). The existing "Research before coding" standard covers researching the codebase. It does not cover researching interaction patterns from established tools. This is Ready-Fire-Aim applied to UX. Claude researches the code but never researches the interaction. **Example:** Siteplanner session (2026-02-19) burned 3+ hours building three wrong delete tools. The correct approach — SketchUp-style independent edge deletion — was obvious once anyone looked. Nobody looked until attempt #3. ### When This Applies Any task involving a new user-facing interaction: draw, select, erase, crop, drag, annotate, measure, snap, resize, undo, zoom-to-fit, tooltip, context menu, keyboard shortcut, or any gesture the user performs with mouse/touch. ### When This Does NOT Apply - Backend changes, API routes, database work - Bug fixes where the interaction already exists and the pattern is confirmed working - Features where Michael has already specified the exact interaction pattern - Styling, layout, or cosmetic changes ### Required Steps **Before proposing any approach:** 1. **Name the interaction pattern.** "This is a segment-delete tool" or "This is a polygon-draw tool" or "This is a drag-to-resize handle." 2. **Research how 2-3 established tools handle it.** SketchUp, Figma, AutoCAD, QGIS, Photoshop, Illustrator, Blender, Google Maps, Leaflet, OpenLayers — whichever are relevant to the domain. 3. **Identify the dominant pattern.** Most established tools converge on the same approach. State what it is. 4. **Present findings.** Brief — tool name, how it handles the interaction, which approach fits this project and why. 5. **Get confirmation.** No code until Michael confirms the interaction design. ### What "Research" Means Here Web search, documentation lookup, or existing knowledge about how the tool works. Not a 30-minute literature review. The goal is to find the established pattern in under 5 minutes, not to write a survey paper. The SketchUp eraser example: one search, one answer, done. The problem was never researching at all. ### Examples | Task | Research Target | Likely Answer | |------|----------------|---------------| | "Add an eraser tool" | SketchUp, Figma, Illustrator | Decompose to edges, click to delete | | "Add polygon drawing" | QGIS, Google Maps, Leaflet | Click vertices, double-click to close | | "Add drag-to-resize" | Figma, CSS, native OS | Corner/edge handles, shift for aspect ratio | | "Add measurement tool" | AutoCAD, SketchUp, Google Earth | Click two points, display distance | | "Add snap-to-grid" | SketchUp, AutoCAD, Figma | Configurable grid, visual snap indicator | --- ## Part 4: The Six Handoff Failure Modes Reference catalog. When a handoff fails, identify which mode and fix that specific problem. ### 1. Too Fat, Wrong Priority The handoff is multi-page. The next session runs out of context or gets lost in background before reaching the task. **Fix:** First line is the next action. One page max. ### 2. Wrong Facts Carried Forward IPs, paths, URLs, or commands that don't work. Copied from memory or earlier docs without verification. **Fix:** Test every fact before including it. Flag unverified items. ### 3. Acknowledged But Not Followed Next session reads the handoff, restates it, then asks questions the handoff already answered. **Fix:** The handoff should end with "Do this first" — not "Here's the context." The next session's first response should be work, not a summary. ### 4. Dead Links Temp URLs expire between sessions. **Fix:** Use permanent links or RAG clips. ### 5. No Handoff Exists Previous session ended without creating one. Next session searches blindly and finds the wrong conversation. **Fix:** Every session that touches code or makes decisions should produce a handoff — even a 5-line one. ### 6. Status Report Instead of Briefing Lists what was built without stating what to do next. The next session has inventory but no direction. **Fix:** "What's not done" and "Next action" are mandatory sections. "What exists" is supporting context. --- ## Memory Edit (for userPreferences) Compact version for Claude's memory system: > **Pre-Build UX Research:** Before coding any new user-facing interaction (draw, select, erase, drag, measure, etc.), research how 2-3 established tools handle the same pattern (SketchUp, Figma, AutoCAD, QGIS, etc.). Present findings. Get confirmation before coding. Does NOT apply to backend, bug fixes, or interactions Michael has already specified. > **Handoff Standard:** Every coding session ends with a handoff. Line 1 = next action. Max one page. Verify all paths/IPs/URLs. Use permanent links. Push summary clip to memsys RAG. State what works vs. what's untested. Do not restate the handoff back to Michael.