handoff-docs

Handoff Docs Skill

When to use

• The user asks to save a spec, design doc, ADR, guide, or note so it survives across sessions
• The user wants to import an existing pile of Markdown files (e.g. a wiki/ or specs/ directory) into structured document management
• You need to read a specific section of a large document without pulling the whole thing into context
• You need to trace how documents relate to each other (parent/child hierarchy, or semantic links like "this design implements that spec")
• A document should be linked to one or more tasks so it surfaces automatically while that task is being worked on

If the knowledge is a short, standalone lesson/rule/convention/gotcha (< 1 page, no internal sections), use handoff-memory instead — see "Memory vs Documents" in skills/handoff-memory/SKILL.md for the boundary.

Development Flow Integration

Document management is NOT just for explicit user requests. It activates automatically during the standard development cycle:

When writing a spec or design

After writing/updating a specification or finishing a /design-review session (wiki/ or tmp/), immediately:

1. Start from a template (see "Templates" below) instead of a blank document.
2. handoff_doc_save(slug="unique-spec-slug", title=..., body=..., doc_type="spec", task_ids=[...])
3. handoff_doc_verify(doc_id=..., action="generate") to create the verification matrix

When starting a task

Before implementation, fetch related specs:

• handoff_doc_query(task_id="<task-id>") — surfaces linked documents automatically
• Review the verification matrix: handoff_doc_verify_status(doc_id=...)

When implementation is complete

Mark verified sections:

• handoff_doc_verify(doc_id=..., action="check", fragment_seq=N) for each completed section
• handoff_doc_verify(doc_id=..., action="set_refs", fragment_seq=N, impl_refs=[...]) to record implementation locations

When reviewing

Check readiness:

• handoff_task_checklist(task_id=..., action="view") — combined readiness view