name	documentation-updater
description	Update all project documentation including implementation docs, user guides, API docs, and architecture diagrams. Use when finalizing features to ensure comprehensive documentation.
allowed-tools	Read, Write, Edit, Grep, Glob, Bash

Documentation Updater Skill

Purpose

This skill provides systematic guidance for updating all types of project documentation when finalizing feature implementations, ensuring comprehensive, accurate, and well-structured documentation.

When to Use

After feature implementation and validation are complete
Need to document implementation details
Creating or updating user guides
Updating API documentation
Adding architecture diagrams
Documenting configuration changes

Documentation Update Workflow

1. Implementation Documentation

Objective: Document how the feature was implemented for developers and maintainers.

Location: docs/implementation/issue-<number>-<feature-name>.md

Template:

# Implementation: Issue #<number> - <Feature Name>

## Overview
Brief description of what was implemented and why.

## Solution Approach
Detailed explanation of the implementation approach:
- Architecture pattern used (e.g., repository pattern, service layer)
- Key design decisions and rationale
- Trade-offs considered
- Alternative approaches rejected and why

## Architecture

### Component Structure

src/tools/feature/ ├── init.py # Public API exports ├── models.py # Data models (Pydantic) ├── interfaces.py # Abstract interfaces ├── core.py # Business logic ├── repository.py # Data access layer ├── validators.py # Input validation └── exceptions.py # Custom exceptions


### Data Flow
[Describe how data flows through the system]

### Key Components

#### ComponentName
- **Purpose**: [What it does]
- **Responsibilities**: [What it's responsible for]
- **Dependencies**: [What it depends on]

## Implementation Details

### Models
[Document Pydantic models and their fields]

### Business Logic
[Document core algorithms and workflows]

### Data Access
[Document repository methods and database interactions]

### Validation
[Document validation rules and error handling]

## Security Measures
- **Authentication**: [How auth is handled]
- **Authorization**: [Permission checks implemented]
- **Input Validation**: [Validation at entry points]
- **Output Sanitization**: [XSS prevention measures]
- **Data Protection**: [Encryption, secure storage]
- **Secrets Management**: [How secrets are handled]

## Performance Optimizations
- **Caching**: [Caching strategy if applicable]
- **Database**: [Query optimization, indexing]
- **Async Operations**: [Use of async/await]
- **Resource Management**: [Memory, connections]
- **Response Times**: [Measured response times]

## Testing
- **Unit Test Coverage**: [percentage]%
- **Integration Tests**: [what's covered]
- **Security Tests**: [auth, validation, etc.]
- **Performance Tests**: [benchmarks met]
- **Edge Cases**: [scenarios tested]

## Configuration
Environment variables required:
```bash
FEATURE_API_KEY=your_api_key
FEATURE_TIMEOUT=30
FEATURE_DEBUG=false

Dependencies

New dependencies added:

package-name==version: [reason for dependency]

Breaking Changes

[List any breaking changes or "None"]

Migration Notes

[Steps needed to migrate or "None required"]

Known Issues

[Issue 1]: [Description and workaround]

Future Enhancements

References

Original Issue: #
Pull Request: #
Related Issues: #
Design Document: docs/architecture/.md


**Actions**:
1. Create implementation doc using template
2. Fill in all sections thoroughly
3. Add code examples where helpful
4. Include diagrams for complex flows
5. Document all security and performance measures

**Deliverable**: Complete implementation documentation

---

### 2. User-Facing Documentation

**Objective**: Update documentation that end users and developers will read to use the feature.

#### README Updates

**Location**: `README.md`

**Check if updates needed**:
- Does the feature change installation steps?
- Does it add new CLI commands?
- Does it change configuration?
- Does it add new user-facing features?

**Actions**:
1. Read current README
2. Identify sections needing updates
3. Add new sections if needed
4. Update code examples
5. Verify all links work

**Example addition**:
```markdown
## New Feature: <Feature Name>

Description of what the feature does.

### Usage

```bash
# Example command
llm-tool feature-command --option value

Configuration

Add to your config file:

feature:
  enabled: true
  option: value

Example

from llms.feature import FeatureService

service = FeatureService()
result = service.do_something()


#### User Guides

**Location**: `docs/guides/<feature-name>-guide.md`

**Create guide for complex features**:
```markdown
# <Feature Name> User Guide

## Introduction
What is this feature and who is it for?

## Getting Started

### Prerequisites
- Requirement 1
- Requirement 2

### Installation
```bash
pip install required-package

Basic Setup

llm-tool init feature-name

Usage

Basic Example

# Simple example
from llms.feature import Feature

feature = Feature()
result = feature.process(data)

Advanced Usage

Use Case 1:

[Step-by-step instructions]

Use Case 2:

[Step-by-step instructions]

Configuration Options

Option	Type	Default	Description
option1	str	"default"	What it does

Troubleshooting

Common Issues

Problem: Error message or issue Solution: How to fix it

Best Practices

Practice 1
Practice 2

Examples

Example 1:

Full working example with explanation

Example 2:

Another complete example

FAQ

Q: Question? A: Answer.

References

API Documentation: [link]
Implementation: [link]


**Deliverable**: User guides for new features

---

### 3. API Documentation

**Objective**: Document API endpoints and interfaces.

#### REST API Documentation

**Location**: `docs/api/<feature-name>-api.md`

**For REST APIs**:
```markdown
# <Feature Name> API

## Base URL

https://api.example.com/v1


## Authentication
```bash
Authorization: Bearer <token>

Endpoints

GET /feature/resource

Get a resource.

Request:

GET /feature/resource?param=value
Authorization: Bearer <token>

Response (200 OK):

{
  "id": 1,
  "name": "example",
  "value": 123
}

Error Responses:

401 Unauthorized: Missing or invalid token
404 Not Found: Resource not found

POST /feature/resource

Create a resource.

Request:

POST /feature/resource
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "example",
  "value": 123
}

Response (201 Created):

{
  "id": 1,
  "name": "example",
  "value": 123,
  "created_at": "2024-01-01T00:00:00Z"
}

Rate Limiting

Rate limit: 100 requests per minute
Header: X-RateLimit-Remaining

Error Codes

Code	Meaning
400	Bad Request - Invalid input
401	Unauthorized - Missing/invalid auth
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error


#### Python API Documentation

**Update docstrings** to be comprehensive:
```python
def create_feature(
    name: str,
    value: int,
    options: Optional[Dict[str, Any]] = None
) -> Feature:
    """
    Create a new feature resource.

    This function creates a feature with the given name and value,
    applying optional configuration if provided.

    Args:
        name: The feature name (1-100 characters, alphanumeric)
        value: The feature value (must be non-negative)
        options: Optional configuration dict with keys:
            - timeout (int): Request timeout in seconds (default: 30)
            - retry (bool): Whether to retry on failure (default: True)

    Returns:
        Feature: Created feature instance with:
            - id: Auto-generated unique identifier
            - name: The provided name
            - value: The provided value
            - created_at: Timestamp of creation

    Raises:
        ValueError: If name is empty or value is negative
        ValidationError: If options are invalid
        APIError: If API request fails

    Examples:
        Basic usage:
        >>> feature = create_feature("example", 123)
        >>> print(feature.id)
        1

        With options:
        >>> feature = create_feature(
        ...     "example",
        ...     123,
        ...     options={"timeout": 60, "retry": False}
        ... )

    Note:
        Feature names must be unique within the system.
        The function performs input validation before API calls.

    See Also:
        - get_feature(): Retrieve existing feature
        - update_feature(): Modify existing feature
        - delete_feature(): Remove feature
    """
    pass

Deliverable: Complete API documentation

4. Architecture Documentation

Objective: Document architectural decisions and system design.

Location: docs/architecture/<feature-name>-architecture.md

When needed:

Complex features with multiple components
New architectural patterns introduced
Significant design decisions made

Template:

# Architecture: <Feature Name>

## Context
Why was this architecture needed?

## Architecture Overview

### System Diagram

┌─────────────┐ │ Client │ └──────┬──────┘ │ ┌──────▼──────────┐ │ API Layer │ └──────┬──────────┘ │ ┌──────▼──────────┐ │ Service Layer │ └──────┬──────────┘ │ ┌──────▼──────────┐ │ Repository │ └──────┬──────────┘ │ ┌──────▼──────────┐ │ Data Store │ └─────────────────┘


### Components

#### API Layer
- **Responsibility**: Handle HTTP requests/responses
- **Technology**: FastAPI/Flask
- **Key Files**: `api/endpoints.py`

#### Service Layer
- **Responsibility**: Business logic
- **Technology**: Pure Python
- **Key Files**: `core.py`

#### Repository Layer
- **Responsibility**: Data access
- **Technology**: SQLAlchemy/File System
- **Key Files**: `repository.py`

## Design Decisions

### Decision 1: <Decision>
**Context**: [Why this decision was needed]
**Options Considered**:
1. Option A: [Description] - Rejected because [reason]
2. Option B: [Description] - **Selected** because [reason]

**Consequences**:
- Positive: [benefit]
- Negative: [trade-off]

### Decision 2: <Decision>
[Same format]

## Data Flow

### Create Flow

Client sends POST request with data
API layer validates request format
Service layer validates business rules
Repository persists data
Response returned to client


### Read Flow
[Describe]

## Security Architecture
- Authentication: [mechanism]
- Authorization: [RBAC, ABAC, etc.]
- Data Protection: [encryption, etc.]

## Performance Considerations
- Caching: [strategy]
- Scaling: [horizontal/vertical]
- Bottlenecks: [identified and mitigated]

## Integration Points
- System A: [how it integrates]
- System B: [how it integrates]

## Future Considerations
- Scalability: [how to scale]
- Evolution: [how to extend]

Deliverable: Architecture documentation with diagrams

5. Configuration Documentation

Objective: Document all configuration options and environment variables.

Update these files:

README.md: Configuration section
docs/guides/configuration.md: Detailed config guide
.env.example: Example environment file

Example .env.example update:

# Feature Name Configuration
FEATURE_API_KEY=your_api_key_here
FEATURE_TIMEOUT=30  # Request timeout in seconds
FEATURE_CACHE_TTL=3600  # Cache time-to-live in seconds
FEATURE_DEBUG=false  # Enable debug logging
FEATURE_MAX_RETRIES=3  # Maximum retry attempts

Configuration guide:

## Configuration Options

### Required Settings

#### FEATURE_API_KEY
- **Type**: string
- **Required**: Yes
- **Description**: API key for authentication
- **Example**: `sk_live_xxxxxxxxxxxx`
- **Where to get**: [URL to get API key]

### Optional Settings

#### FEATURE_TIMEOUT
- **Type**: integer
- **Required**: No
- **Default**: 30
- **Description**: Request timeout in seconds
- **Valid range**: 1-300

## Configuration Methods

### Environment Variables
```bash
export FEATURE_API_KEY=your_key

Config File

# config.yaml
feature:
  api_key: your_key
  timeout: 30

Programmatic

from llms.feature import configure

configure(api_key="your_key", timeout=30)


**Deliverable**: Complete configuration documentation

---

### 6. TECH-STACK Updates

**Objective**: Document new dependencies added.

**Location**: `TECH-STACK.md`

**Add entries for new dependencies**:
```markdown
### <Feature Name> (Added: YYYY-MM-DD)

**Dependencies**:
- **package-name** (version): [Description of why needed]
  - Purpose: [What it's used for]
  - License: [MIT, Apache, etc.]
  - Alternatives considered: [Other options]

**Security Considerations**:
- Vulnerability scan: [Clean/Issues found]
- Maintenance status: [Active/Inactive]

Deliverable: Updated TECH-STACK.md

Documentation Checklist

Use this checklist to ensure comprehensive documentation:

Implementation Documentation

Implementation doc created in docs/implementation/
Solution approach documented
Architecture and components described
Security measures documented
Performance optimizations noted
Testing coverage detailed
Configuration requirements listed
Dependencies documented
Breaking changes noted
Migration notes provided (if applicable)

User Documentation

README.md updated (if applicable)
User guide created (for complex features)
Usage examples provided
Configuration options documented
Troubleshooting section added
All code examples tested and working

API Documentation

API endpoints documented (if REST API)
Request/response formats shown
Error codes documented
Authentication documented
Rate limiting noted
Python API docstrings complete

Architecture Documentation

Architecture doc created (if complex feature)
System diagrams included
Design decisions documented
Data flows described
Integration points noted

Configuration Documentation

.env.example updated
Configuration guide updated
All options documented with types/defaults
Configuration methods shown

Technical Documentation

TECH-STACK.md updated (if dependencies added)
Dependencies documented with rationale
Security considerations noted

Quality Checks

All links tested and working
Code examples tested
Markdown properly formatted
No spelling/grammar errors
Version numbers consistent
Screenshots current (if applicable)

Best Practices

Writing Style

Use clear, concise language
Write in present tense
Use active voice
Avoid jargon where possible
Define technical terms on first use

Code Examples

Test all code examples
Use realistic, meaningful examples
Include imports and setup
Show expected output
Handle errors in examples

Organization

Follow logical structure
Use consistent heading levels
Group related content
Cross-reference related docs
Maintain table of contents for long docs

Maintenance

Date all documentation
Note version numbers
Link to issues/PRs
Mark deprecated features
Update on changes

Common Documentation Patterns

Feature Introduction

## <Feature Name>

<One-line description>

### Overview
<Paragraph explaining what it does and why it's useful>

### Quick Start
<Minimal example to get started>

### Learn More
- [User Guide](link)
- [API Documentation](link)
- [Examples](link)

Code Example Pattern

### Example: <Scenario>

<Brief description of what this example demonstrates>

```python
# Import required modules
from llms.feature import Feature

# Initialize
feature = Feature(option="value")

# Use the feature
result = feature.process(data)

# Handle result
print(result)

Output:

Expected output here

Explanation:


### Troubleshooting Pattern
```markdown
### Common Issues

#### Issue: <Error message or problem>

**Symptoms**:
- What the user sees
- Error messages

**Cause**:
Why this happens

**Solution**:
1. Step to fix
2. Another step
3. Verify it's fixed

**Prevention**:
How to avoid this issue

Supporting Resources

Reference materials for documentation:

Markdown Guide: https://www.markdownguide.org/
Google Developer Documentation Style Guide
Write the Docs: https://www.writethedocs.org/

Integration with Deployment Flow

Input: Completed, validated feature implementation Process: Systematic documentation of all aspects Output: Comprehensive documentation across all types Next Step: Changelog generation

Example Workflow

# 1. Create implementation documentation
Write docs/implementation/issue-123-user-auth.md

# 2. Update README if needed
Edit README.md to add authentication section

# 3. Create user guide for complex feature
Write docs/guides/authentication-guide.md

# 4. Update API documentation
Edit docs/api/authentication-api.md

# 5. Document architecture if complex
Write docs/architecture/auth-architecture.md

# 6. Update configuration docs
Edit .env.example to add AUTH_* variables
Edit docs/guides/configuration.md

# 7. Update TECH-STACK.md if dependencies added
Edit TECH-STACK.md to add new auth libraries

# 8. Verify all links work
Check all cross-references and external links

# 9. Test all code examples
Run each code example to ensure they work

# 10. Review checklist
Ensure all items checked off

Quality Standards

Documentation is complete when:

All checklist items verified
Code examples tested and working
Links verified
Markdown properly formatted
Spelling/grammar checked
Version numbers consistent
Cross-references complete
User perspective considered

Install Skill

SKILL.md

Documentation Updater Skill

Purpose

When to Use

Documentation Update Workflow

1. Implementation Documentation

Dependencies

Breaking Changes

Migration Notes

Known Issues

Future Enhancements

References

Configuration

Example

Basic Setup

Usage

Basic Example

Advanced Usage

Use Case 1:

Use Case 2:

Configuration Options

Troubleshooting

Common Issues

Best Practices

Examples

Example 1:

Example 2:

FAQ

References

Endpoints

GET /feature/resource

POST /feature/resource

Rate Limiting

Error Codes

4. Architecture Documentation

5. Configuration Documentation

Config File

Programmatic

Documentation Checklist

Implementation Documentation

User Documentation

API Documentation

Architecture Documentation

Configuration Documentation

Technical Documentation

Quality Checks

Best Practices

Writing Style

Code Examples

Organization

Maintenance

Common Documentation Patterns

Feature Introduction

Code Example Pattern

Supporting Resources

Integration with Deployment Flow

Example Workflow

Quality Standards