Documentation Generation Skill

Generate comprehensive Confluence documentation from Jira issues, Harness PRs, and code implementations.

When to Activate

This skill activates when:

• User requests documentation for a feature
• PR is created and needs documentation
• User asks to document an issue or implementation
• Sprint/release documentation is needed
• Technical design docs are required

Document Types

1. Feature Documentation

For new features and major changes:

# {Feature Name}

## Overview
Brief description of the feature and its purpose.

## Background
### Problem Statement
What problem does this solve?

### Related Issues
- [PROJ-123](jira_link) - Main feature issue
- [PROJ-124](jira_link) - Subtask 1
- [PROJ-125](jira_link) - Subtask 2

## Technical Design

### Architecture
```mermaid
flowchart LR
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    C --> D[User DB]

Components

API Changes

New Endpoints

• POST /api/auth/login - User login
• POST /api/auth/register - User registration

Request/Response Examples

// POST /api/auth/login
Request:
{
  "email": "user@example.com",
  "password": "..."
}

Response:
{
  "token": "eyJ...",
  "expires_in": 3600
}

Implementation Details

Key Files Changed

• src/auth/login.ts - Login logic
• src/auth/register.ts - Registration logic
• src/middleware/auth.ts - Auth middleware

Database Changes

ALTER TABLE users ADD COLUMN refresh_token VARCHAR(255);

Testing

Test Coverage

• Unit tests: 95%
• Integration tests: 12 scenarios
• E2E tests: 5 user flows

How to Test Manually

1. Navigate to /login
2. Enter credentials
3. Verify token received

Deployment

Prerequisites

• Database migration required
• Environment variables: JWT_SECRET, TOKEN_EXPIRY

Rollback Plan

1. Revert database migration
2. Deploy previous version
3. Clear token cache

References

• PR #45 - Implementation PR
• Design Doc - Original design
• API Spec - OpenAPI specification

### 2. Technical Design Document

For complex implementations:

```markdown
# Technical Design: {Feature Name}

## Document Info
| Field | Value |
|-------|-------|
| Author | {author} |
| Status | Draft / In Review / Approved |
| Issue | [PROJ-123](link) |
| Last Updated | {date} |

## Executive Summary
One paragraph summary of the design.

## Goals and Non-Goals

### Goals
- ✅ Implement user authentication
- ✅ Support JWT tokens
- ✅ Include refresh token mechanism

### Non-Goals
- ❌ Social login (future phase)
- ❌ Multi-factor authentication (separate initiative)

## Background
Context and motivation for this design.

## Detailed Design

### System Architecture
Description of the overall architecture.

### Component Design
Detailed design for each component.

### Data Model

┌─────────────────────────────┐ │ Users │ ├─────────────────────────────┤ │ id: UUID (PK) │ │ email: VARCHAR(255) │ │ password_hash: VARCHAR(255) │ │ refresh_token: VARCHAR(255) │ │ created_at: TIMESTAMP │ │ updated_at: TIMESTAMP │ └─────────────────────────────┘

### API Design
OpenAPI specification or detailed endpoint descriptions.

### Security Considerations
- Token expiry and rotation
- Password hashing (bcrypt)
- Rate limiting

## Alternatives Considered

### Option A: Session-based Auth
**Pros:** Simpler implementation
**Cons:** Not suitable for API-first architecture

### Option B: OAuth 2.0
**Pros:** Industry standard
**Cons:** Overkill for current needs

### Decision
JWT-based auth chosen for balance of simplicity and flexibility.

## Implementation Plan

### Phase 1: Core Auth (Week 1)
- Login/logout endpoints
- JWT generation

### Phase 2: Registration (Week 1-2)
- Registration endpoint
- Email verification

### Phase 3: Token Refresh (Week 2)
- Refresh token mechanism
- Token rotation

## Testing Strategy
How the implementation will be tested.

## Monitoring and Alerting
What metrics and alerts will be added.

## Open Questions
- Should we support remember-me functionality?
- What should the token expiry be?

3. API Documentation

For API changes:

# API Documentation: {Service Name}

## Authentication
All endpoints require Bearer token authentication.

Authorization: Bearer

## Endpoints

### POST /api/auth/login

Authenticate a user and receive an access token.

**Request Body**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address |
| password | string | Yes | User's password |

**Response**
| Field | Type | Description |
|-------|------|-------------|
| token | string | JWT access token |
| refresh_token | string | Refresh token |
| expires_in | number | Token expiry in seconds |

**Example**
```bash
curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "..."}'

Errors

## Generation Process

### Step 1: Gather Information

Collect from multiple sources:

1. **Jira Issue**:

mcp__atlassian__jira_get_issue(issue_key)

- Summary, description
- Acceptance criteria
- Comments and discussion

2. **Harness PR**:

mcp__harness__get_pullreq(pr_number)

- PR description
- Changed files
- Review comments

3. **Code Analysis**:
- Read changed files
- Extract API signatures
- Identify patterns

### Step 2: Generate Content

Based on document type:

1. Select appropriate template
2. Fill in sections from gathered data
3. Generate diagrams if needed
4. Add code examples

### Step 3: Create in Confluence

mcp__atlassian__confluence_create_page({ space: "PROJ", title: "Feature: User Authentication", parent_id: "123456", content: generated_content })

### Step 4: Link Back

1. Add Confluence link to Jira issue
2. Add Confluence link to PR description
3. Notify team in comment

## Confluence Spaces

| Space | Purpose | Documents |
|-------|---------|-----------|
| PROJ | Project documentation | Feature docs, decisions |
| TECH | Technical documentation | Design docs, architecture |
| API | API documentation | Endpoint references |
| RUN | Runbooks | Operational guides |

## Templates

Templates are stored in `${CLAUDE_PLUGIN_ROOT}/templates/`:

- `feature-doc.md` - Feature documentation
- `design-doc.md` - Technical design
- `api-doc.md` - API documentation
- `runbook.md` - Operational runbook
- `adr.md` - Architecture Decision Record

## Best Practices

1. **Keep Updated**: Docs should be updated with code changes
2. **Link Everything**: Cross-link Jira, PRs, and Confluence
3. **Include Examples**: Code examples are essential
4. **Version Control**: Note which version docs apply to
5. **Review**: Docs should be reviewed with code