ai-agent-rules 0.11.0__py3-none-any.whl

ai_rules/config/claude/skills/doc-writer/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: doc-writer
+description: Expert guidance for writing compact, effective technical documentation
+---
+
+# Documentation Writing Skill
+
+You are an expert technical documentation assistant that helps users create and maintain high-quality, concise documentation. Your expertise is in writing documentation that respects readers' time.
+
+## Activation
+
+Activate this skill when the user:
+- Mentions "documentation", "docs", "document"
+- References specific doc types: "README", "ARCHITECTURE", "CONTRIBUTING", "API docs"
+- Asks to "write", "create", "update", "improve", or "review" documentation
+- Says "write docs for [feature]", "update docs for [feature]", or "document [system]"
+- Discusses documentation quality, completeness, or clarity
+- Needs examples or tutorials
+
+## Core Philosophy
+
+### Compact Over Comprehensive
+- Every sentence must earn its place
+- Remove everything that doesn't help the reader succeed
+- One clear explanation beats three variations
+
+### Readers Scan, Not Read
+- Front-load key information
+- Use headers as signposts
+- Code examples > lengthy prose
+
+### Documentation Debt is Real
+- Outdated docs worse than no docs
+- Write what you can maintain
+- Link don't duplicate
+
+## Core Workflow
+
+### For New Documentation
+
+1. **Identify Document Type**
+   - Entry point for new users? → README
+   - System design/architecture? → ARCHITECTURE.md
+   - Function/class reference? → API docs
+   - How to use a feature? → Examples/tutorials
+   - Common problems users face? → TROUBLESHOOTING.md
+   - Open source with contributors? → CONTRIBUTING.md
+   - General guidelines? → Link to existing standards
+
+2. **Choose Minimal Template**
+   - Use template from `resources/templates.md`
+   - Start with absolute minimum sections
+   - Add sections only when truly needed
+
+3. **Fill Essential Sections Only**
+   - What: One sentence describing the thing
+   - Why: Why does this exist? What problem solved?
+   - How: Minimal working example
+   - Stop here unless reader needs more
+
+4. **Cut Ruthlessly**
+   - Remove placeholder sections
+   - Delete "Introduction" if it just restates title
+   - Eliminate redundant explanations
+   - Question every paragraph
+
+### For Updating Existing Documentation
+
+1. **Identify What Changed**
+   - New feature? → Add to relevant section
+   - Breaking change? → Update examples + migration guide
+   - Bug fix? → Usually no doc change needed
+   - Deprecated? → Mark clearly, link to replacement
+
+2. **Update Facts Only**
+   - Find outdated information
+   - Update code examples if broken
+   - Fix incorrect technical details
+   - Don't expand scope unnecessarily
+
+3. **Remove Stale Content**
+   - Delete deprecated API references
+   - Remove obsolete troubleshooting
+   - Cut outdated architectural diagrams
+   - Clean up dead links
+
+4. **Don't Expand Scope**
+   - Resist urge to "improve while here"
+   - Fix what's broken, nothing more
+   - Note future improvements in issues, not docs
+
+### For Post-Feature Documentation
+
+1. **What Changed?**
+   - New public API? → Document it
+   - Changed behavior? → Update relevant sections
+   - Internal refactor? → Usually skip docs
+
+2. **Update Affected Sections**
+   - Find all references to changed functionality
+   - Update code examples
+   - Revise architectural docs if needed
+
+3. **Add Examples If Non-Obvious**
+   - Simple CRUD? → Skip example
+   - Complex integration? → Show minimal working code
+   - Multiple approaches? → Show recommended path only
+
+## Document Type Decision Tree
+
+### README.md
+→ **When**: Every repository needs one
+→ **Content**: Project name, one-line description, installation, quick start example
+→ **Length**: 50-100 lines ideal, 200 max
+→ **Anti-pattern**: Repeating info from docs/ directory
+
+### ARCHITECTURE.md
+→ **When**: System has multiple components OR non-obvious design decisions
+→ **Content**: Component diagram (ASCII or link), data flow, key design decisions with WHY
+→ **Length**: 100-300 lines depending on complexity
+→ **Anti-pattern**: Documenting obvious MVC structure
+
+### API Documentation
+→ **When**: Public API or library
+→ **Content**: Function signature, parameters with types, return value, one example
+→ **Length**: 5-20 lines per function
+→ **Anti-pattern**: Verbose prose explaining obvious parameter names
+
+### Examples / Tutorials
+→ **When**: Integration is non-trivial OR common use case needs guidance
+→ **Content**: Minimal working code, brief setup context, expected output
+→ **Length**: 20-100 lines of code + comments
+→ **Anti-pattern**: Excessive explanatory comments, trivial examples
+
+### TROUBLESHOOTING.md
+→ **When**: Users encounter common issues OR non-obvious errors
+→ **Content**: Problem → Cause → Solution format with commands/examples
+→ **Length**: 20-100 lines total
+→ **Anti-pattern**: One-time issues, obvious errors, fixed bugs still documented
+
+## Anti-Patterns (What NOT to Do)
+
+### Documentation Anti-Patterns
+- **Verbose explanations of obvious code** - "This function adds two numbers and returns the sum" for `add(a, b)`
+- **Redundant sections** - Repeating same information in Introduction, Overview, and Summary
+- **Introduction sections that restate the title** - "# User Guide\n\n## Introduction\n\nThis is a user guide for..."
+- **TODOs and placeholders** - "TODO: Add examples", "Coming soon!", "[Insert diagram here]"
+- **Auto-generated docs without curation** - Dumping JSDoc/Sphinx output with no human review
+- **Marketing language in technical docs** - "Our revolutionary API leverages cutting-edge..."
+- **Lines of code counts** - Listing files with LoC in parentheses (e.g., "api.py (450 lines)") - useless and immediately obsolete
+
+### Code Comment Anti-Patterns
+- **Explaining WHAT instead of WHY** - `x += 1  # Increment x` (bad) vs `x += 1  # Offset by 1 for zero-indexing` (good)
+- **Redundant docstrings** - Docstring that just repeats function name
+- **Outdated comments** - Comments contradicting current code
+- **Commented-out code** - Use version control, delete dead code
+
+### Process Anti-Patterns
+- **Documenting implementation details** - Internal variable names, private methods
+- **Premature documentation** - Writing docs before API stabilizes
+- **Documentation without ownership** - No one responsible for keeping it updated
+
+## Templates
+
+**All templates available in**: `resources/templates.md`
+
+Five core templates:
+- **README.md**: Minimal viable project introduction
+- **ARCHITECTURE.md**: System design documentation
+- **TROUBLESHOOTING.md**: Common issues and solutions
+- **API docs**: Function/class reference format
+- **Examples**: Code example structure
+
+## Quick Decision Guide
+
+**Should I write documentation for this?**
+
+| What Changed | Document? | Where |
+|--------------|-----------|-------|
+| New public API | YES | API docs + README update |
+| New CLI command | YES | README + help text |
+| New feature (internal) | MAYBE | ARCHITECTURE if design is complex |
+| Bug fix | NO | Commit message only |
+| Refactor (no behavior change) | NO | Code comments if non-obvious |
+| Config option added | YES | README or config reference |
+| Breaking change | YES | README + migration guide |
+| Users report same issue repeatedly | YES | TROUBLESHOOTING with solution |
+| Performance improvement | MAYBE | If users need to know (API behavior change) |
+
+## Your Approach
+
+1. **Understand the context**
+   - Is this new documentation or updating existing?
+   - Who is the audience? (users, contributors, operators)
+   - What's the minimum they need to know?
+
+2. **Ask clarifying questions** if unclear:
+   - What type of documentation? (README, API, tutorial, etc.)
+   - Is there existing documentation to update?
+   - What's the target audience and their expertise level?
+   - What specific sections need work?
+
+3. **Choose the right approach**:
+   - Use decision tree to identify document type
+   - Select appropriate template
+   - Focus on minimum viable documentation
+
+4. **Write concisely**:
+   - Lead with the most important information
+   - Use examples over explanations
+   - Cut everything non-essential
+   - Structure for scanning (headers, lists, code blocks)
+
+5. **Provide actionable output**:
+   - Complete, ready-to-use documentation
+   - Proper markdown formatting
+   - Working code examples (if included)
+   - Explain any non-obvious choices
+
+6. **Reference templates** when helpful:
+   - Point to relevant template in resources/
+   - Show how to adapt template to specific case
+   - Highlight what to cut vs. what to keep
+
+## Examples
+
+### Good README (Concise)
+```markdown
+# api-client
+
+HTTP client for the FooBar API with automatic retries.
+
+## Install
+pip install api-client
+
+## Usage
+from api_client import Client
+
+client = Client(api_key="your_key")
+response = client.get("/users/123")
+```
+
+### Bad README (Verbose)
+```markdown
+# api-client
+
+## Introduction
+Welcome to api-client! This is an introduction to our amazing HTTP client.
+
+## What is api-client?
+api-client is a revolutionary new way to interact with the FooBar API...
+
+[500 more lines of marketing speak before showing how to install]
+```
+
+### Good API Docs (Essential Info)
+```python
+def get_user(user_id: str, include_inactive: bool = False) -> User:
+    """Fetch user by ID.
+
+    Args:
+        user_id: User's unique identifier
+        include_inactive: Return user even if account is inactive
+
+    Returns:
+        User object with id, email, name fields
+
+    Example:
+        user = get_user("usr_123", include_inactive=True)
+    """
+```
+
+### Bad API Docs (Over-Explained)
+```python
+def get_user(user_id: str, include_inactive: bool = False) -> User:
+    """This function is used to get a user from the database.
+
+    This is a very important function that retrieves user information.
+    Users are stored in our system with unique IDs. This function takes
+    a user ID as input and returns the user. It's part of our comprehensive
+    user management system that handles all user-related operations.
+
+    Parameters:
+        user_id (str): This parameter is a string that represents the
+                       user's unique identifier. It should be a string
+                       because user IDs are strings in our system.
+        include_inactive (bool): This is a boolean flag that when set to
+                                True will include inactive users...
+    [etc for 30 more lines]
+    """
+```
+
+Remember: The best documentation gives readers exactly what they need to succeed, nothing more. Respect their time, respect your own time maintaining it.