docs: emphasize navigation over completeness in handoff notes

Amolith created 

Restructure Lunatask skill to clarify that handoff notes are navigation
aids for future agents, not solutions. Add explicit guidance on what to
include (entry points, constraints) and what to avoid (code blocks,
exhaustive context).

Assisted-by: Claude Opus 4.5 via Crush <crush@charm.land>

Change summary

skills/deferring-work-through-lunatask/SKILL.md | 45 ++++++++++++++++--
1 file changed, 38 insertions(+), 7 deletions(-)

Detailed changes

skills/deferring-work-through-lunatask/SKILL.md 🔗 

@@ -7,6 +7,34 @@ metadata:
   author: Amolith <amolith@secluded.site>
 ---
 
+## Purpose
+
+Handoff notes are **navigation aids**, not solutions. A future agent will read this note in a fresh context window and explore the _current_ state of the codebase. Your job is to point it in the right direction, not do its thinking for it.
+
+Why this matters:
+
+- Code changes between now and when the task is picked up
+- Pasted code blocks become stale and misleading
+- The receiving agent builds better understanding by exploring than by inheriting your conclusions
+- Shorter handoffs mean the receiving agent has more context budget for actual work
+
+## What to include
+
+1. The goal: one or two sentences describing what needs to happen
+2. Entry points: specific file paths and line ranges where the receiving agent should start reading (e.g., `pkg/auth/tokens.go:45-80`, not the contents of those lines)
+3. Recent changes: brief description of what we just did that creates this need (so the agent understands the "before" state)
+4. Discovered constraints: non-obvious gotchas, API limitations, or decisions that aren't evident from the code
+5. References: links to issues, commits, docs, or prior handoffs that informed this work
+
+## What NOT to include
+
+- Code blocks longer than ~5 lines: if you're tempted to paste implementation, paste the file path instead
+- Complete solutions: the receiving agent should derive these from current code state
+- Exhaustive context: only what's necessary to orient, not everything you learned
+- Copied file contents: always reference by path, never by content
+
+If you find yourself writing something that would let someone complete the task by copy-pasting from the note, you've gone too far. Back up and replace content with references.
+
 ## Formatting
 
 ### Title
@@ -25,8 +53,6 @@ New tasks usually get status `later`.
 
 ### Note structure
 
-Use `[Title](lunatask://...)` syntax if deep links are needed.
-
 ```markdown
 > [Warm, direct message to user—make them smile when they find this later]
 
@@ -34,16 +60,21 @@ Use `[Title](lunatask://...)` syntax if deep links are needed.
 
 Hello, future me! o/
 
-[Thorough description of the work: what needs doing, why it matters, relevant context discovered during the session]
+[Goal: 1-2 phrase description of what needs doing]
 
-[Follow our slow and methodical planning approach: read relevant source code, documentation, and APIs before acting]
+Start here:
 
-When starting this task, update status according to workflow. When finished, mark `complete`.
+- `path/to/file.go:XX-YY` — [why this location matters]
+- `another/file.go:ZZ` — [what to look for here]
 
-ID: PLACEHOLDER_ID
+[Context: describe what we just did that led to the need for a hand-off. What constraints or gotchas we discovered. Keep this to a short paragraph.]
+
+[Optional approach hints: high-level suggestions only—"consider X" not "implement X by doing Y". If the approach is obvious from the goal + entry points, omit this.]
+
+When starting this task, update status according to workflow. When finished, mark `complete`.
 ```
 
-After creation, update the note to replace `PLACEHOLDER_ID` with the actual task ID from the creation response.
+After creation, refer to the task with [title](lunatask://deep/link) syntax.
 
 ### References trailer