handoff-docs

Handoff Docs Skill

Structured project documents under .handoff/docs/: one Markdown file per document, indexed by section, searchable, linked to tasks and to each other.

• Per-tool parameters: references/doc-tools.md
• Section verification matrix and doc_req_* requirements: references/verification-matrix.md
• V-model layer documents (requirements → specs → tests with coverage, suspects, approval): the handoff-trace skill (overview, setup) and the handoff-requirements skill (how to write items)

When to use

• The user asks to save a spec, design, plan, ADR, guide or note so it survives across sessions — or you write one during development
• Importing an existing directory of Markdown (specs/, docs/) at once
• Reading one section of a large document without loading all of it
• Following how documents relate (parent/child, "implements", "supersedes")
• Linking a document to tasks so it surfaces while those tasks are worked on

A short standalone lesson/rule/gotcha (under a page, no sections) belongs in project memory instead — see the handoff-memory skill and "Memory vs Documents" below.

Choose a tracking style first

A layer document's items come from its body headings; the section matrix's add_item / set_priority / set_refs(test_refs) and doc_req_import are refused on it. Pick one style per document.

If the project uses the V-model ([trace] profile is set — check handoff_get_config), save specs and designs with a layer, or enable [trace] auto_layer so doc_save infers one: spec → requirement, design → detailed_spec, plan → detailed_spec (override with [trace] plan_default_layer); adr / guide / note never get one. An explicit layer always wins ("" clears it and suppresses inference for that call). For layers the table does not cover (basic_spec, acceptance, …), always pass layer explicitly.