specweave 0.26.4 → 0.26.9

package/plugins/specweave-docs/skills/technical-writing/SKILL.md

@@ -5,335 +5,377 @@ description: Technical writing expert for API documentation, README files, tutor
 
 # Technical Writing Skill
 
-Expert in technical documentation, API reference writing, tutorials, and developer-focused content. Specializes in clear, concise, and comprehensive documentation that developers actually use.
+**Self-contained technical documentation expertise for ANY user project.**
+
+Expert in developer-focused documentation: READMEs, API references, tutorials, and changelogs.
+
+---
 
 ## Core Documentation Types
 
 ### 1. README Files
 
-**Essential Sections**:
-
+**Essential Structure**:
 ```markdown
 # Project Name
 
-One-sentence description of what this project does.
+One-sentence description.
 
 ## Features
-
 - Key feature 1
 - Key feature 2
-- Key feature 3
 
 ## Installation
-
 ```bash
 npm install project-name
 ```
 
 ## Quick Start
-
 ```javascript
 import { ProjectName } from 'project-name';
-
 const instance = new ProjectName();
-instance.doSomething();
 ```
 
 ## Usage
-
-### Basic Example
-
-[Runnable code example]
-
-### Advanced Example
-
-[More complex use case]
+[Basic example]
 
 ## API Reference
-
-Link to detailed API docs or inline reference.
-
-## Configuration
-
-Available options and their defaults.
+[Link or inline reference]
 
 ## Contributing
-
-Link to CONTRIBUTING.md
+[Link to CONTRIBUTING.md]
 
 ## License
-
-MIT (or your license)
+MIT
 ```
 
 **Best Practices**:
-- **Lead with value**: What problem does this solve?
-- **Show, don't tell**: Code examples > long explanations
-- **Progressive disclosure**: Quick start → Advanced features
-- **Keep it updated**: Sync with actual code behavior
-
-**Examples**:
+- Lead with value (what problem solved?)
+- Code examples > long explanations
+- Progressive disclosure (quick start → advanced)
+- Keep updated with code
 
-**Bad README**:
-```markdown
-# My Project
-
-This is a library.
-
-## Installation
-npm install
+### 2. API Documentation
 
-## Usage
-Use it in your code.
+**Function/Method Documentation**:
+```typescript
+/**
+ * Compress image with quality settings
+ *
+ * @param {string} input - Path to input image
+ * @param {CompressOptions} options - Compression options
+ * @param {number} options.quality - Quality 0-100 (default: 80)
+ * @param {string} options.format - Output format: jpeg|png|webp
+ *
+ * @returns {Promise<CompressResult>} Compression result with saved bytes
+ *
+ * @example
+ * const result = await compress('photo.jpg', { quality: 90 });
+ * console.log(`Saved ${result.savedBytes} bytes`);
+ */
 ```
 
-**Good README**:
+**REST API Documentation**:
 ```markdown
-# Image Optimizer
+### POST /api/users
 
-Compress images up to 80% without visible quality loss. Supports JPEG, PNG, WebP.
+Create a new user.
 
-## Installation
+**Request**:
+```json
+{
+  "email": "user@example.com",
+  "name": "John Doe"
+}
+```
 
-```bash
-npm install image-optimizer
+**Response** (201 Created):
+```json
+{
+  "id": "uuid",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "created": "2025-11-24T12:00:00Z"
+}
 ```
 
-## Quick Start
+**Errors**:
+- 400: Invalid email format
+- 409: Email already exists
+```
 
-```javascript
-import { optimize } from 'image-optimizer';
+### 3. Tutorials
 
-// Compress a single image
-const result = await optimize('input.jpg', {
-  quality: 80,
-  format: 'webp'
-});
-console.log(`Saved ${result.savedBytes} bytes`);
-```
+**Structure**:
+```markdown
+# Tutorial: Build X in 10 Minutes
 
-## Features
+**You'll learn**:
+- How to set up X
+- Core concepts
+- Build a working example
 
-- ✅ Lossless and lossy compression
-- ✅ Batch processing (parallel)
-- ✅ Format conversion (JPEG → WebP, PNG → AVIF)
-- ✅ Preserves EXIF metadata
-- ✅ CLI and Node.js API
+**Prerequisites**:
+- Node.js 18+
+- Basic JavaScript knowledge
 
-## CLI Usage
+## Step 1: Setup
 
 ```bash
-image-optimizer input.jpg --quality 80 --format webp
+npm create vite@latest my-project
+cd my-project
+npm install
 ```
 
-## API
+## Step 2: Create Component
 
-### `optimize(input, options)`
+[Code with explanation]
 
-Compress a single image.
+## Step 3: Test It
 
-**Parameters**:
-- `input` (string): Path to input image
-- `options` (object):
-  - `quality` (number, 0-100): Compression quality (default: 80)
-  - `format` (string): Output format - `jpeg`, `png`, `webp` (default: auto-detect)
+[How to run and verify]
 
-**Returns**: `Promise<OptimizeResult>`
+## Next Steps
 
-**Example**:
-```javascript
-const result = await optimize('photo.jpg', { quality: 90 });
-```
+- Advanced feature 1
+- Advanced feature 2
+- Link to API docs
 ```
 
-### 2. API Documentation
+**Best Practices**:
+- State prerequisites up front
+- Break into small, testable steps
+- Show expected output at each step
+- Link to related docs
 
-#### RESTful API Documentation
+### 4. Changelogs
 
+**Keep a Changelog Format** (keepachangelog.com):
 ```markdown
-# API Reference
+# Changelog
 
-Base URL: `https://api.example.com/v1`
+All notable changes to this project will be documented in this file.
 
-## Authentication
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-All requests require an API key in the header:
+## [Unreleased]
 
-```bash
-Authorization: Bearer YOUR_API_KEY
-```
+### Added
+- New feature X for Y use case
 
-## Endpoints
+### Changed
+- Improved performance of Z by 40%
 
-### Get User
+### Fixed
+- Critical bug in authentication (CVE-2024-1234)
 
-Retrieve user details by ID.
+## [1.2.0] - 2025-11-24
 
-**Endpoint**: `GET /users/:id`
+### Added
+- Real-time notifications via WebSocket
+- Export to PDF functionality
 
-**Parameters**:
-- `id` (path parameter, required): User ID (UUID v4)
+### Changed
+- Updated dependencies (React 19)
 
-**Headers**:
-- `Authorization: Bearer <token>` (required)
+### Deprecated
+- `oldMethod()` - use `newMethod()` instead
 
-**Example Request**:
-```bash
-curl -H "Authorization: Bearer abc123" \
-  https://api.example.com/v1/users/550e8400-e29b-41d4-a716-446655440000
-```
+### Removed
+- Legacy API v1 endpoints
 
-**Success Response (200 OK)**:
-```json
-{
-  "id": "550e8400-e29b-41d4-a716-446655440000",
-  "email": "user@example.com",
-  "name": "John Doe",
-  "created_at": "2024-01-15T10:30:00Z",
-  "status": "active"
-}
-```
+### Fixed
+- Memory leak in image processing
+- CORS issue with production domain
 
-**Error Responses**:
+### Security
+- Fixed SQL injection vulnerability (CVE-2025-5678)
 
-**404 Not Found** - User does not exist
-```json
-{
-  "error": "USER_NOT_FOUND",
-  "message": "No user found with ID 550e8400-e29b-41d4-a716-446655440000"
-}
-```
+## [1.1.0] - 2025-11-01
 
-**401 Unauthorized** - Invalid or missing API key
-```json
-{
-  "error": "UNAUTHORIZED",
-  "message": "Invalid API key"
-}
+[Previous release notes]
 ```
 
-**Rate Limiting**:
-- 100 requests per minute per API key
-- Header `X-RateLimit-Remaining` shows remaining requests
-- Returns `429 Too Many Requests` when exceeded
+**Categories**:
+- **Added**: New features
+- **Changed**: Changes in existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Now removed features
+- **Fixed**: Bug fixes
+- **Security**: Vulnerability fixes
 
 ---
 
-### Create User
+## Style Guide Essentials
 
-Create a new user account.
+### Voice & Tone
 
-**Endpoint**: `POST /users`
+**Active Voice** (preferred):
+- ✅ "The function returns an array"
+- ❌ "An array is returned by the function"
 
-**Headers**:
-- `Content-Type: application/json` (required)
-- `Authorization: Bearer <token>` (required)
+**Present Tense** (preferred):
+- ✅ "The API validates input"
+- ❌ "The API will validate input"
 
-**Request Body**:
-```json
-{
-  "email": "user@example.com",      // required, valid email
-  "name": "John Doe",                // required, 1-100 chars
-  "password": "SecurePass123!",      // required, min 8 chars
-  "role": "user"                     // optional, default: "user"
-}
-```
+**Second Person** (for tutorials):
+- ✅ "You can configure the timeout"
+- ❌ "Users can configure the timeout"
 
-**Validation Rules**:
-- Email must be unique
-- Password must contain: 8+ chars, 1 uppercase, 1 number, 1 special char
-- Role must be one of: `user`, `admin`, `moderator`
+### Clarity Rules
 
-**Example Request**:
-```bash
-curl -X POST https://api.example.com/v1/users \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer abc123" \
-  -d '{"email":"user@example.com","name":"John Doe","password":"SecurePass123!"}'
-```
+**Be Specific**:
+- ✅ "Set timeout to 5000ms"
+- ❌ "Set a reasonable timeout"
 
-**Success Response (201 Created)**:
-```json
-{
-  "id": "550e8400-e29b-41d4-a716-446655440000",
-  "email": "user@example.com",
-  "name": "John Doe",
-  "role": "user",
-  "created_at": "2024-01-15T10:30:00Z"
-}
+**Avoid Jargon** (or explain it):
+- ✅ "Idempotent (can be called multiple times safely)"
+- ❌ "The endpoint is idempotent"
+
+**Short Sentences**:
+- ✅ "Install the package. Then import it."
+- ❌ "After installing the package, you need to import it into your project."
+
+### Code Examples
+
+**Show Complete Examples**:
+```javascript
+// ✅ GOOD - Complete, runnable
+import { connect } from 'database';
+
+const db = await connect({
+  host: 'localhost',
+  port: 5432
+});
+
+const users = await db.query('SELECT * FROM users');
+console.log(users);
 ```
 
-**Error Responses**:
+```javascript
+// ❌ BAD - Incomplete
+db.query('SELECT * FROM users');
+```
 
-**400 Bad Request** - Validation error
-```json
-{
-  "error": "VALIDATION_ERROR",
-  "message": "Email already exists",
-  "field": "email"
+**Include Error Handling**:
+```javascript
+// ✅ GOOD
+try {
+  const result = await processImage('photo.jpg');
+  console.log('Success:', result);
+} catch (error) {
+  console.error('Failed to process image:', error.message);
 }
 ```
 
-**422 Unprocessable Entity** - Password complexity
-```json
-{
-  "error": "INVALID_PASSWORD",
-  "message": "Password must contain at least one special character",
-  "field": "password"
-}
+---
+
+## Documentation Structure
+
+### Information Architecture
+
+**Organize by User Journey**:
+```
+docs/
+├── getting-started/
+│   ├── installation.md
+│   ├── quick-start.md
+│   └── first-project.md
+├── guides/
+│   ├── authentication.md
+│   ├── deployment.md
+│   └── troubleshooting.md
+├── api-reference/
+│   ├── client.md
+│   ├── server.md
+│   └── types.md
+└── examples/
+    ├── basic-crud.md
+    ├── real-time-updates.md
+    └── advanced-queries.md
 ```
+
+**Progressive Disclosure**:
+1. **Getting Started**: Quickest path to value
+2. **Guides**: Task-oriented how-tos
+3. **API Reference**: Complete technical reference
+4. **Examples**: Real-world patterns
+
+### Navigation Best Practices
+
+**Clear Hierarchy**:
+- Use consistent heading levels (H1 → H2 → H3)
+- Don't skip heading levels
+- One H1 per page
+
+**Cross-Linking**:
+- Link to related docs
+- Link to prerequisites
+- Link to next steps
+
+**Table of Contents** (for long pages):
+```markdown
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Basic Example](#basic-example)
+  - [Advanced Example](#advanced-example)
+- [API Reference](#api-reference)
 ```
 
-#### OpenAPI/Swagger Specification
+---
+
+## OpenAPI / Swagger
+
+### OpenAPI 3.0 Template
 
 ```yaml
 openapi: 3.0.0
 info:
-  title: Example API
+  title: User API
   version: 1.0.0
-  description: API for user management
+  description: User management API
 
 servers:
   - url: https://api.example.com/v1
 
 paths:
-  /users/{id}:
+  /users:
     get:
-      summary: Get user by ID
-      description: Retrieve detailed user information
-      operationId: getUser
-      tags:
-        - Users
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: string
-            format: uuid
-          description: User ID (UUID v4)
+      summary: List all users
       responses:
         '200':
-          description: User found
+          description: Successful response
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/User'
-        '404':
-          description: User not found
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+
+    post:
+      summary: Create user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUser'
+      responses:
+        '201':
+          description: User created
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: '#/components/schemas/User'
 
 components:
   schemas:
     User:
       type: object
-      required:
-        - id
-        - email
-        - name
       properties:
         id:
           type: string
@@ -343,697 +385,149 @@ components:
           format: email
         name:
           type: string
-          minLength: 1
-          maxLength: 100
-        created_at:
-          type: string
-          format: date-time
-        status:
-          type: string
-          enum: [active, inactive, suspended]
 
-    Error:
+    CreateUser:
       type: object
       required:
-        - error
-        - message
+        - email
+        - name
       properties:
-        error:
-          type: string
-        message:
+        email:
           type: string
-        field:
+          format: email
+        name:
           type: string
 ```
 
-### 3. Tutorials and Guides
-
-**Structure**:
-
-```markdown
-# Tutorial: Building Your First Widget
-
-**Estimated Time**: 20 minutes
-**Prerequisites**: Node.js 18+, npm 9+
-**What You'll Build**: A real-time notification widget
-
-## What You'll Learn
-
-- How to initialize a widget instance
-- How to configure event handlers
-- How to style widgets with CSS
-- How to deploy to production
-
 ---
 
-## Step 1: Installation
+## Documentation Maintenance
 
-Install the widget library:
-
-```bash
-npm install widget-library
-```
+### Versioning Strategy
 
-**Expected Output**:
+**Version docs alongside code**:
 ```
-+ widget-library@1.0.0
-added 1 package
+docs/
+├── v1.0/
+│   ├── api.md
+│   └── guides.md
+├── v2.0/
+│   ├── api.md
+│   ├── guides.md
+│   └── migration.md
+└── latest/ → symlink to v2.0/
 ```
 
----
+**Migration Guides**:
+```markdown
+# Migrating from v1 to v2
 
-## Step 2: Create Basic Widget
+## Breaking Changes
 
-Create a new file `widget.js`:
+### Authentication
 
+**v1**:
 ```javascript
-import { Widget } from 'widget-library';
-
-const widget = new Widget({
-  container: '#app',
-  theme: 'light'
-});
-
-widget.render();
+const api = new API({ token: 'abc123' });
 ```
 
-**What's Happening Here?**
-- `container`: CSS selector for mounting point
-- `theme`: Visual theme (light/dark)
-- `render()`: Displays the widget on the page
-
-**Try It**: Open `index.html` in a browser. You should see a blank widget.
-
----
-
-## Step 3: Add Event Handlers
-
-Update `widget.js` to handle notifications:
-
+**v2**:
 ```javascript
-widget.on('notification', (data) => {
-  console.log('New notification:', data.message);
-});
-
-// Simulate a notification
-widget.notify({
-  message: 'Hello, World!',
-  type: 'info'
+const api = new API({
+  auth: { bearer: 'abc123' }
 });
 ```
 
-**Expected Behavior**:
-- Console logs: "New notification: Hello, World!"
-- Widget displays a blue info box
-
----
-
-## Step 4: Customize Styles
-
-Create `widget.css`:
-
-```css
-.widget {
-  border: 2px solid #3498db;
-  border-radius: 8px;
-  padding: 16px;
-}
-
-.widget-notification {
-  background: #ecf0f1;
-  color: #2c3e50;
-}
-```
-
-**Result**: Widget now has rounded corners and custom colors.
-
----
-
-## Troubleshooting
-
-**Problem**: Widget doesn't appear
-- ✅ Check that `#app` element exists in HTML
-- ✅ Verify `widget.render()` is called
-- ✅ Open browser console for errors
-
-**Problem**: Notifications don't show
-- ✅ Ensure event handler is registered before calling `notify()`
-- ✅ Check notification type is valid (`info`, `warning`, `error`)
-
----
-
-## Next Steps
-
-- [Advanced Configuration](./advanced-config.md)
-- [Custom Themes](./themes.md)
-- [Production Deployment](./deployment.md)
-
----
-
-## Complete Code
-
-```javascript
-// widget.js
-import { Widget } from 'widget-library';
-
-const widget = new Widget({
-  container: '#app',
-  theme: 'light'
-});
-
-widget.on('notification', (data) => {
-  console.log('New notification:', data.message);
-});
+### What Changed
+- `token` parameter renamed to `auth.bearer`
+- Supports multiple auth methods now
 
-widget.render();
+### Migration Steps
 
-widget.notify({
-  message: 'Hello, World!',
-  type: 'info'
-});
-```
+1. Update API initialization
+2. Test authentication flow
+3. Update error handling (new error codes)
 ```
 
-**Tutorial Best Practices**:
-- **Show progress**: Step numbers, estimated time
-- **Explain why**: Don't just show code, explain reasoning
-- **Checkpoints**: "At this point, you should see..."
-- **Troubleshooting**: Anticipate common errors
-- **Complete examples**: Provide runnable code
-
-### 4. Changelog Management
-
-**Keep a Changelog Format** (semantic versioning):
-
-```markdown
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- Feature X for improved performance
-- New `debugMode` configuration option
-
-### Changed
-- Updated default timeout from 5s to 10s
-
-### Deprecated
-- `oldMethod()` will be removed in v3.0.0 (use `newMethod()` instead)
-
-### Fixed
-- Bug where cache wasn't invalidated on updates
-
----
-
-## [2.1.0] - 2024-01-15
+### Keep Docs Fresh
 
-### Added
-- WebSocket support for real-time updates
-- TypeScript type definitions
-- Retry logic with exponential backoff
-
-### Changed
-- **BREAKING**: `config.timeout` now in milliseconds (was seconds)
-- Improved error messages with context
+**Automation**:
+- Generate API docs from code (JSDoc, TypeDoc, OpenAPI)
+- Auto-update version numbers in docs
+- CI/CD checks for broken links
 
-### Fixed
-- Memory leak in connection pool
-- Race condition in concurrent requests
+**Review Checklist**:
+- [ ] Code examples run without errors
+- [ ] All links work (no 404s)
+- [ ] Version numbers match package.json
+- [ ] Screenshots show current UI
+- [ ] Deprecation warnings added for old features
 
 ---
 
-## [2.0.0] - 2023-12-01
+## Common Pitfalls
 
-### Added
-- Complete rewrite with TypeScript
-- Plugin system for extensibility
+**❌ Avoid**:
+- Outdated examples (don't run)
+- Missing prerequisites
+- Incomplete code snippets
+- Vague error messages ("something went wrong")
+- Over-explaining obvious things
+- Using future tense ("will do X")
 
-### Removed
-- **BREAKING**: Removed deprecated `legacyMode` option
+**✅ Do**:
+- Test all code examples
+- State prerequisites up front
+- Show complete, runnable code
+- Specific error messages with fixes
+- Respect reader's intelligence
+- Use present tense
 
 ---
 
-## [1.5.2] - 2023-11-10
+## Quick Reference Templates
 
-### Fixed
-- Security vulnerability in dependency (CVE-2023-XXXXX)
-
----
-
-## [1.5.1] - 2023-11-05
-
-### Fixed
-- Incorrect version number in package.json
-```
-
-**Changelog Best Practices**:
-- **Categorize changes**: Added, Changed, Deprecated, Removed, Fixed, Security
-- **Link to issues**: `Fixed #123` links to GitHub issue
-- **Breaking changes**: Mark with **BREAKING** prefix
-- **Security fixes**: Separate category, include CVE if applicable
-- **Date format**: ISO 8601 (YYYY-MM-DD)
-
-### 5. Code Comments and Inline Documentation
-
-**JSDoc Example**:
-
-```typescript
+### Function Documentation
+```javascript
 /**
- * Compress an image file with optional format conversion.
- *
- * @param input - Path to input image file
- * @param options - Compression options
- * @returns Promise resolving to compression result
- *
- * @throws {ImageNotFoundError} If input file doesn't exist
- * @throws {UnsupportedFormatError} If format is not supported
+ * Brief description
  *
+ * @param {Type} paramName - Description
+ * @returns {Type} Description
+ * @throws {ErrorType} When/why
  * @example
- * ```typescript
- * const result = await compress('photo.jpg', {
- *   quality: 80,
- *   format: 'webp'
- * });
- * console.log(`Saved ${result.savedBytes} bytes`);
- * ```
- *
- * @see {@link https://docs.example.com/compression} for compression algorithm details
- */
-export async function compress(
-  input: string,
-  options: CompressOptions
-): Promise<CompressResult> {
-  // Implementation
-}
-
-/**
- * Options for image compression
+ * functionName(arg);
  */
-export interface CompressOptions {
-  /**
-   * Compression quality (0-100)
-   * @default 80
-   */
-  quality?: number;
-
-  /**
-   * Output format
-   * @default 'jpeg' (auto-detected from input)
-   */
-  format?: 'jpeg' | 'png' | 'webp' | 'avif';
-
-  /**
-   * Preserve EXIF metadata
-   * @default true
-   */
-  preserveMetadata?: boolean;
-}
-```
-
-**Python Docstrings (Google Style)**:
-
-```python
-def compress_image(input_path, quality=80, format='jpeg'):
-    """Compress an image file with optional format conversion.
-
-    Args:
-        input_path (str): Path to input image file.
-        quality (int, optional): Compression quality (0-100). Defaults to 80.
-        format (str, optional): Output format ('jpeg', 'png', 'webp').
-            Defaults to 'jpeg'.
-
-    Returns:
-        CompressResult: Object containing output path and bytes saved.
-
-    Raises:
-        FileNotFoundError: If input_path doesn't exist.
-        ValueError: If quality not in range 0-100.
-        UnsupportedFormatError: If format is not supported.
-
-    Examples:
-        >>> result = compress_image('photo.jpg', quality=90, format='webp')
-        >>> print(f"Saved {result.saved_bytes} bytes")
-        Saved 1234567 bytes
-
-    See Also:
-        compress_batch: For compressing multiple images in parallel.
-    """
-    pass
-```
-
-## Style Guides
-
-### 1. Microsoft Writing Style Guide Principles
-
-- **Concise**: Remove filler words ("basically", "simply", "just")
-- **Active voice**: "The function returns" > "The value is returned by"
-- **Present tense**: "The system validates" > "The system will validate"
-- **Second person**: "You can configure" > "Users can configure"
-- **Avoid jargon**: Define acronyms on first use
-
-**Examples**:
-
-❌ **Bad**: "Basically, the API will simply return a JSON object containing all of the user data."
-✅ **Good**: "The API returns a JSON object with user data."
-
-❌ **Bad**: "The request is processed by the server, and then the response is sent."
-✅ **Good**: "The server processes the request and sends a response."
-
-### 2. Technical Terminology
-
-**Consistent Capitalization**:
-- API (not Api, api)
-- JavaScript (not Javascript, javascript)
-- TypeScript (not Typescript, typescript)
-- macOS (not MacOS, Mac OS)
-- Node.js (not NodeJS, nodejs)
-
-**Abbreviations**:
-- Define on first use: "Single Page Application (SPA)"
-- Use consistently: Either "HTTP" or "http", not both
-
-**Code Elements**:
-- Inline code: Use backticks - "The `setTimeout()` function..."
-- File names: Use backticks - "Edit `config.json`"
-- Commands: Use code blocks with language hint
-
-### 3. Information Architecture
-
-**Progressive Disclosure**:
-
-```
-Level 1: Overview (What & Why)
-  ├─ Level 2: Quick Start (How - Minimal)
-  ├─ Level 3: Tutorials (How - Detailed)
-  ├─ Level 4: Reference (Comprehensive)
-  └─ Level 5: Advanced Topics
-```
-
-**Example Structure**:
-
-```
-Documentation Root
-├── Getting Started
-│   ├── Installation
-│   ├── Quick Start (5 min)
-│   └── Core Concepts
-├── Tutorials
-│   ├── Tutorial 1: Basic Usage
-│   ├── Tutorial 2: Advanced Features
-│   └── Tutorial 3: Production Deployment
-├── API Reference
-│   ├── Functions
-│   ├── Classes
-│   └── Types
-├── How-To Guides
-│   ├── Authentication
-│   ├── Error Handling
-│   └── Performance Optimization
-└── Advanced
-    ├── Architecture
-    ├── Contributing
-    └── Troubleshooting
 ```
 
-## Documentation Tools
-
-### 1. Markdown Variants
-
-**GitHub Flavored Markdown (GFM)**:
-
+### CLI Command Documentation
 ```markdown
-## Task Lists
-- [x] Completed task
-- [ ] Pending task
+### command [options]
 
-## Tables
-| Header 1 | Header 2 |
-|----------|----------|
-| Cell 1   | Cell 2   |
-
-## Syntax Highlighting
-```javascript
-const x = 10;
-```
+Description of what command does.
 
-## Alerts (GitHub)
-> [!NOTE]
-> Useful information
-
-> [!WARNING]
-> Critical content
-
-> [!IMPORTANT]
-> Key information
-```
-
-### 2. Documentation Generators
-
-**TypeDoc (TypeScript)**:
-
-```bash
-npm install --save-dev typedoc
-
-# Generate docs
-npx typedoc --out docs src/index.ts
-```
-
-**Sphinx (Python)**:
-
-```bash
-pip install sphinx
+**Options**:
+- `-f, --flag`: Description (default: value)
+- `-o, --option <value>`: Description
 
-# Initialize
-sphinx-quickstart docs
-
-# Build
-cd docs && make html
-```
-
-**JSDoc (JavaScript)**:
-
-```bash
-npm install --save-dev jsdoc
-
-# Generate docs
-npx jsdoc -c jsdoc.json src/
-```
-
-### 3. Versioned Documentation (Docusaurus)
-
-```bash
-npm run docusaurus docs:version 1.0.0
-
-# Creates:
-# - versioned_docs/version-1.0.0/
-# - versioned_sidebars/version-1.0.0-sidebars.json
-```
-
-## Best Practices
-
-### 1. Write for Scanning, Not Reading
-
-**Use**:
-- Headings and subheadings
-- Bullet lists (not paragraphs)
-- Code examples (not long explanations)
-- Visual hierarchy (bold, italics, code blocks)
-
-**Example**:
-
-❌ **Bad**:
-```
-The configuration file is a JSON file that contains various options for
-the application. You can set the timeout option to control how long the
-application waits before timing out. The default value is 5000 milliseconds.
-```
-
-✅ **Good**:
-```
-## Configuration
-
-Edit `config.json`:
-
-```json
-{
-  "timeout": 5000  // milliseconds, default: 5000
-}
-```
-```
-
-### 2. Show, Don't Tell
-
-❌ **Bad**: "You can use the function to fetch user data."
-✅ **Good**:
-```javascript
-const user = await fetchUser('123');
-console.log(user.name); // "John Doe"
-```
-
-### 3. Provide Context
-
-❌ **Bad**:
-```javascript
-widget.setOption('cache', true);
-```
-
-✅ **Good**:
-```javascript
-// Enable caching to reduce API calls by 80% (recommended for production)
-widget.setOption('cache', true);
-```
-
-### 4. Test Your Documentation
-
-- **Run examples**: Ensure all code snippets actually work
-- **Fresh eyes**: Ask someone unfamiliar with the project to follow docs
-- **Automated checks**: Lint markdown, validate links, test code snippets
-
-### 5. Keep It Updated
-
-- **Deprecation warnings**: Document what's changing and when
-- **Migration guides**: Provide step-by-step upgrade instructions
-- **Version compatibility**: State which versions docs apply to
-
-## Common Mistakes to Avoid
-
-### 1. Assuming Knowledge
-
-❌ **Bad**: "Just use the OAuth flow"
-✅ **Good**: "Authenticate using OAuth 2.0 (see [tutorial](link))"
-
-### 2. Implementation Over Outcome
-
-❌ **Bad**: "This function uses a binary search algorithm"
-✅ **Good**: "This function finds elements in O(log n) time"
-
-### 3. Missing Error Cases
-
-❌ **Bad**: Only documenting success responses
-✅ **Good**: Document all HTTP status codes (200, 400, 401, 404, 500)
-
-### 4. Outdated Examples
-
-❌ **Bad**: Examples using deprecated APIs
-✅ **Good**: Update examples with each release
-
-### 5. No Searchability
-
-❌ **Bad**: PDF documentation (not searchable)
-✅ **Good**: HTML docs with search functionality (Algolia, local search)
-
-## Templates
-
-### API Endpoint Template
-
-```markdown
-### [HTTP Method] [Endpoint Path]
-
-[One-sentence description]
-
-**Endpoint**: `[METHOD] /path/:param`
-
-**Authentication**: [Required/Optional]
-
-**Parameters**:
-- `param1` (type, location): Description
-
-**Request Body** (if applicable):
-```json
-{
-  "field": "value"
-}
-```
-
-**Success Response ([Status Code])**:
-```json
-{
-  "result": "data"
-}
-```
-
-**Error Responses**:
-- **[Status Code]**: Description
-```json
-{
-  "error": "ERROR_CODE"
-}
-```
-
-**Rate Limiting**: [Limits]
-
-**Example**:
+**Examples**:
 ```bash
-curl [example command]
+command --flag --option=value
 ```
 ```
 
-### Tutorial Template
-
+### Error Documentation
 ```markdown
-# Tutorial: [Goal]
-
-**Time**: [Estimate]
-**Prerequisites**: [Requirements]
-**What You'll Build**: [Outcome]
-
-## What You'll Learn
-
-- Bullet list
-
----
-
-## Step 1: [Action]
+### Error: ECONNREFUSED
 
-[Instructions]
+**Cause**: Cannot connect to database
 
-```code
-[Example]
+**Solutions**:
+1. Check database is running: `docker ps`
+2. Verify connection string in `.env`
+3. Check firewall allows port 5432
 ```
 
-**Expected Result**: [What should happen]
-
----
-
-[Repeat steps]
-
----
-
-## Troubleshooting
-
-**Problem**: [Issue]
-- ✅ Solution 1
-- ✅ Solution 2
-
 ---
 
-## Next Steps
-
-- [Related tutorial]
-- [Advanced topic]
-```
-
-## Resources
-
-- [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
-- [Google Developer Documentation Style Guide](https://developers.google.com/style)
-- [Write the Docs](https://www.writethedocs.org/)
-- [Keep a Changelog](https://keepachangelog.com/)
-
-## Activation Keywords
-
-Ask me about:
-- "How to write API documentation"
-- "README best practices"
-- "Technical writing style guide"
-- "Changelog format and versioning"
-- "Tutorial structure and examples"
-- "OpenAPI/Swagger documentation"
-- "JSDoc and code comments"
-- "Developer documentation tips"
-- "How to write clear technical docs"
+**This skill is self-contained and works in ANY user project.**