diff --git a/.pi/skills/to-document b/.pi/skills/to-document new file mode 120000 index 0000000..6b2e42d --- /dev/null +++ b/.pi/skills/to-document @@ -0,0 +1 @@ +../../src/skills/to-document \ No newline at end of file diff --git a/docs/TODO.md b/docs/TODO.md index 3f0b45c..647393c 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -34,7 +34,6 @@ - claude-code/review-uncommitted - claude-code/setup-skills - claude-code/test-driven-development - - claude-code/to-spec - claude-code/to-tasks - claude-code/update-skills - implement diff --git a/src/skills/to-document/DOCUMENT-FORMAT.md b/src/skills/to-document/DOCUMENT-FORMAT.md new file mode 100644 index 0000000..e31cdbf --- /dev/null +++ b/src/skills/to-document/DOCUMENT-FORMAT.md @@ -0,0 +1,62 @@ +# Document Format + +## Template + +```md +## Problem Statement + +The problem that the user is facing, from the user's perspective. + +## Solution + +The solution to the problem, from the user's perspective. + +## User Stories + +An extensive, numbered list of user stories, covering all aspects of the feature. Each user story should be in the format of: + +1. As an , I want a , so that + + +1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending + + +## Implementation Decisions + +A list of implementation decisions that were made. This can include: + +- The modules that will be built/modified +- The interfaces of those modules that will be modified +- Technical clarifications from the developer +- Architectural decisions +- Schema changes +- API contracts +- Specific interactions + +## Testing Decisions + +A list of testing decisions that were made. Include: + +- A description of what makes a good test (only test external behavior, not implementation details) +- Which modules will be tested +- Prior art for the tests, that is, similar tests in the codebase + +## Out of Scope + +A description of the things that are out of scope for this spec. + +## Further Notes + +Any further notes about the feature. +``` + +## Rules + +- **Do not include specific file paths or code snippets.** + They can become outdated quickly. + Exception: include a prototype snippet when it records a decision more precisely than prose. + Examples include a state machine, reducer, schema, or type shape. + Inline the snippet in the relevant implementation decision. + Note briefly that the snippet came from a prototype. + Trim the snippet to the decision-rich parts. + Do not include a working demo. diff --git a/src/skills/to-document/SKILL.md b/src/skills/to-document/SKILL.md new file mode 100644 index 0000000..2257383 --- /dev/null +++ b/src/skills/to-document/SKILL.md @@ -0,0 +1,64 @@ +--- +name: to-document +description: 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](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.