tomevault-io Write to Documentation Skill
This skill activates when you need to create or update formal project documentation.
When This Skill Activates
Automatically engage when:
- Writing feature specifications
- Creating architectural decision records (ADRs)
- Documenting review findings
- Writing implementation plans
- Creating interface definitions
- Documenting data models
- Writing knowledge base articles
Documentation Principles
Clarity
- Use clear, precise language
- Define technical terms
- Provide examples where helpful
- Use consistent terminology
Structure
- Follow established templates
- Use clear headings and sections
- Organize information logically
- Include table of contents for long documents
Completeness
- Cover all necessary aspects
- Include context and rationale
- Link to related documents
- Specify version and date
Maintainability
- Keep documentation close to code
- Use relative links for internal references
- Include update dates
- Note document owner/maintainer
Documentation Locations
Feature Specifications
- Location:
docs/features/[feature-name].md - Template:
docs/features/_template.md - Purpose: Formal feature requirements and design
Architectural Decisions
- Location:
docs/architecture/decisions.md(or individual ADR files) - Template:
docs/architecture/_decision-template.md - Purpose: Record important architectural choices
Interface Definitions
- Location:
docs/architecture/interfaces/[api-name].md - Template:
docs/architecture/interfaces/_template.md - Purpose: API contracts and integration specifications
Review Findings
- Location:
ai_docs/reviews/[type]-[subject]-[date].md - Template:
ai_docs/reviews/_template.md - Purpose: Expert review outputs and recommendations
Implementation Plans
- Location:
ai_docs/plans/[feature-name]-plan.md - Purpose: Detailed implementation breakdown
Data Models
- Location:
docs/architecture/models/[model-name].md - Purpose: Database schemas, ERDs, domain models
Knowledge Base
- Location:
ai_docs/knowledge/[topic]/ - Template:
ai_docs/knowledge/_template/ - Purpose: Domain knowledge for agents
Workflow
1. Identify Document Type
Determine what kind of documentation is needed
2. Load Appropriate Template
Use the template for consistency:
Feature Spec → docs/features/_template.md
ADR → docs/architecture/_decision-template.md
Interface → docs/architecture/interfaces/_template.md
Review → ai_docs/reviews/_template.md
3. Fill Template Sections
Complete all required sections:
- Don't skip sections - use "N/A" if truly not applicable
- Provide sufficient detail for implementation
- Include examples and code snippets where helpful
- Link to related documents
4. Use Proper Formatting
Headings
# Document Title (H1 - once per document)
## Major Section (H2)
### Subsection (H3)
#### Detail (H4)
Code Blocks
```language
code here
#### Lists
```markdown
- Unordered item
- Unordered item
1. Ordered item
2. Ordered item
Tables
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data | Data | Data |
Links
[Link Text](relative/path/to/doc.md)
[External Link](https://example.com)
Emphasis
**bold** for strong emphasis
*italic* for emphasis
`code` for inline code
5. Include Metadata
Add document metadata at the top:
**Version:** 1.0.0
**Last Updated:** 2024-01-15
**Status:** Draft | In Review | Approved | Deprecated
**Owner:** Team/Person
6. Cross-Reference Related Docs
Link to:
- Related feature specs
- Relevant ADRs
- Interface definitions
- Architecture documentation
- Previous decisions
7. Save to Correct Location
Follow the location guidelines above
Document Quality Checklist
Before finalizing documentation:
- Uses appropriate template
- All required sections completed
- Clear and concise language
- Technical terms defined
- Examples provided where helpful
- Code snippets included where relevant
- Related documents linked
- Metadata included (version, date, status)
- Saved to correct location
- File naming follows convention
- Formatting consistent
- Spelling and grammar checked
Writing Style
Active Voice
Good: "The system validates user input" Avoid: "User input is validated by the system"
Present Tense
Good: "The function returns a Promise" Avoid: "The function will return a Promise"
Specific Language
Good: "Response time must be less than 200ms" Avoid: "Response should be fast"
Concise Sentences
Good: "Use JWT tokens for authentication." Avoid: "In order to provide authentication capabilities, the system should utilize JWT tokens."
Common Document Types
Feature Specification
Purpose: Define what to build Key Sections: Overview, requirements, user flows, acceptance criteria, technical considerations
ADR (Architectural Decision Record)
Purpose: Record important decisions Key Sections: Context, decision drivers, options considered, decision, consequences
Interface Definition
Purpose: Define API contract Key Sections: Endpoints, request/response formats, error handling, examples
Review Report
Purpose: Document review findings Key Sections: Summary, findings by area, issues by severity, recommendations
Implementation Plan
Purpose: Break down implementation Key Sections: Steps, considerations, risks, success criteria
Examples
Good Feature Spec Section
## User Flow
### Happy Path: User Registration
1. User navigates to `/signup`
2. User fills registration form:
- Email (validated: must contain @, max 254 chars)
- Password (min 10 chars, must include uppercase, lowercase, number)
- Name (min 2 chars, max 100 chars)
3. User clicks "Sign Up"
4. System validates input (client-side)
5. System submits to `POST /api/auth/register`
6. System sends verification email
7. System displays "Check your email" message
8. User clicks verification link in email
9. System activates account
10. System redirects to dashboard
### Error Path: Invalid Email
1-3. [Same as happy path]
4. System detects invalid email format
5. System displays error: "Please enter a valid email address"
6. Focus returns to email field
7. User corrects and resubmits
Good ADR
# ADR 003: Use JWT for Authentication
**Date:** 2024-01-15
**Status:** Accepted
## Context
We need to authenticate users across our web app and mobile apps. We require:
- Stateless authentication
- Support for multiple clients
- Token expiration and refresh
- Scalability to millions of users
## Decision Drivers
- Horizontal scalability (no server-side session storage)
- Mobile app support
- API-first architecture
- Security requirements
## Decision
Use JWT (JSON Web Tokens) for authentication with:
- 15-minute access token expiration
- 7-day refresh token expiration
- RS256 signing algorithm
- Tokens stored in httpOnly cookies for web, secure storage for mobile
## Consequences
### Positive
- Stateless - easy to scale horizontally
- Works across all clients
- Industry standard with good library support
- Self-contained - no database lookup per request
### Negative
- Cannot revoke tokens before expiration
- Token size larger than session IDs
- Need to implement refresh token rotation
- More complex than session-based auth
## Implementation Notes
- Store refresh tokens in database for revocation capability
- Implement token rotation on refresh
- Use short access token expiration for security
- Add token to request header: `Authorization: Bearer {token}`
References
Constraints
- Keep documents focused and purposeful
- Don't document everything - only what adds value
- Update documentation when implementation changes
- Archive outdated documentation rather than deleting
- Link between related documents to avoid duplication
Converted and distributed by TomeVault — claim your Tome and manage your conversions.