dev/src/skills/to-document/SKILL.md

name, description

name	description
to-document	Draft a requested summary, specification, plan, decision record, or similar document from conversation and repository context.

Do not start with an interview when the conversation gives a usable subject. Ask before drafting only when the conversation lacks a usable subject.

Do not put draft contents in the chat response. Always persist the draft to a file.

Do not implement the draft contents unless the operator gives a separate instruction. Treat a completed draft as documentation, not an instruction to build.

Process

1. Identify the subject. Use the conversation as the primary source. If the conversation lacks a usable subject, ask what the document is about. Do not ask clarifying questions before drafting when a usable subject exists.

   Finish when you have a subject or a question that requests the missing subject.

2. Gather repository facts that the draft needs. Inspect files when repository details matter. Do not invent modules, paths, commands, flows, contracts, or conventions. Distinguish confirmed facts from assumptions.

   Finish when each repository-specific claim has support or an explicit assumption marker.

3. Choose the document shape. Infer the document type and title from context. Load DOCUMENT-FORMAT.md when the operator requests no specific format. Adapt the structure only when the requested document type needs different sections. Preserve useful sections for decisions, testing, scope, and notes.

   Finish when the draft has a title and section plan that fit the requested document.

4. Write the draft. Capture known context accurately. Mark assumptions and gaps explicitly. Include decisions that the conversation settled. Include open questions only as gaps, not as an interview. Keep the document focused on the operator's problem and intended use.

   Finish when the draft contains the relevant facts, decisions, assumptions, gaps, and scope.

5. Persist the draft. Use docs/00 INBOX/ai as the default destination. Use the operator's requested path when one exists. Derive a kebab-case slug from the inferred title. Create the destination directory when it does not exist. If the target file exists, summarize the expected change. Confirm before overwriting an existing file. Do not print the draft in chat instead of writing it.

   Finish when the draft is written or overwrite confirmation is pending.

6. Finish with the result. Report the written path. Do not include the draft contents in the response. Do not continue into implementation without an explicit instruction.

   Finish when the operator can find the written draft.