documenting

Documenting

This skill writes reviewable docs with minimal fluff. Default to fewer words. If a sentence does not change scope, decisions, implementation, or review, cut it.

Modes

feature-spec

Use for:

• problem and user need
• scope and non-goals
• requirements
• success criteria
• user or team mental model

Write to:

/docs/features/[feature_name]/YYMMDD_[feature].md

Rules:

• feature_name and [feature] must be kebab-case
• prefix the file with the creation date in YYMMDD_ format
• default [feature] to the same slug as the folder
• preferred pattern:

/docs/features/unified-search/260314_unified-search.md

• if the feature folder already exists, update the latest relevant doc instead of creating a duplicate

Writing rules:

• summary: 2 to 4 sentences
• goals: 3 bullets max
• requirements: 3 to 7 bullets, one sentence each
• mental model: 3 bullets max unless complexity requires more
• open questions: 5 max
• prefer bullets over paragraphs
• do not use filler such as seamless, robust, user-friendly, intuitive, or scalable unless you define what they mean

technical-design

Use for:

• architecture and boundaries
• interfaces and data flow
• implementation approach
• tradeoffs
• rollout, migration, testing, or observability

Write to:

/docs/technical/[technical_design_name]/YYMMDD_[technical_design_name].md

Rules:

• technical_design_name must be kebab-case
• prefix the file with the creation date in YYMMDD_ format
• default the file slug to the same slug as the folder
• preferred pattern:

/docs/technical/session-rotation/260314_session-rotation.md

• if the design folder already exists, update the latest relevant doc instead of creating a duplicate

Writing rules:

• summary: 1 short paragraph
• major decisions: 3 to 5 if possible
• alternatives: only include real contenders
• open questions: unresolved design decisions only
• remove product background that does not affect the design