Confluence Documentation Skill

TEMPLATE: This skill uses {{PLACEHOLDER}} tokens. Replace with your project values before use.

Purpose

Provide standardized templates for creating technical documentation. These templates ensure consistent, high-quality documentation across the project.

When This Skill Applies

• Creating Architecture Decision Records (ADRs)
• Writing operational runbooks
• Documenting system architecture
• Creating technical specifications
• Writing knowledge transfer (KT) documents

ADR Template (Architecture Decision Record)

# ADR-XXX: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
What is the issue that we're seeing that motivates this decision?

## Decision
What is the change that we're proposing and/or doing?

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Tradeoff 1]
- [Tradeoff 2]

### Neutral
- [Observation]

## Implementation Notes
How should this decision be implemented?

## Related Decisions
- ADR-XXX: [Related decision]

## References
- [Link to relevant documentation]

Runbook Template

# Runbook: [Operation Name]

## Overview
Brief description of what this runbook covers.

## Prerequisites
- [ ] Access to [system]
- [ ] Required permissions
- [ ] Tools installed

## Procedure

### Step 1: [Action Name]
[Command to execute]

**Expected output**: Description of what you should see
**If error**: What to do if something goes wrong

### Step 2: [Action Name]
...

## Verification
How to verify the operation was successful.

## Rollback
Steps to undo the operation if needed.

## Troubleshooting

### Issue: [Common problem]
**Symptoms**: What you see
**Cause**: Why it happens
**Solution**: How to fix it

## Contacts
- Primary: [Name/Role]
- Escalation: [Name/Role]

## Revision History
| Date       | Author | Changes         |
| ---------- | ------ | --------------- |
| YYYY-MM-DD | Name   | Initial version |

Architecture Document Template

# [System/Component] Architecture

## Overview
High-level description of the system/component.

## Goals and Non-Goals

### Goals
- [What this system should do]

### Non-Goals
- [What this system should NOT do]

## Architecture Diagram
[ASCII diagram or link to diagram]

## Components

### Component 1: [Name]
- **Purpose**: What it does
- **Location**: Where it lives
- **Dependencies**: What it needs

## Data Flow
How data moves through the system.

## Security Considerations
- Authentication
- Authorization (RLS)
- Data protection

## Performance Considerations
- Caching strategy
- Database optimization
- API response times

## Monitoring and Observability
- Key metrics
- Alerting thresholds
- Log locations

## Future Considerations
What might change or be improved.

## References
- Related ADRs
- External documentation

Knowledge Transfer (KT) Document Template

# KT: [Topic Name] - {{TICKET_PREFIX}}-XXX

## Summary
What was done and why it matters.

## Context
Background information needed to understand this work.

## Key Decisions Made
1. [Decision 1]: [Reasoning]
2. [Decision 2]: [Reasoning]

## Implementation Details

### What Changed
- File: `path/to/file`
  - Change description

### How It Works
Explanation of the implementation.

## Gotchas and Lessons Learned
Things that might trip up future developers.

## Testing
How to verify everything works.

## Related Tickets
- {{TICKET_PREFIX}}-XXX: [Related work]

## Future Work
What should be done next.

Documentation Output Locations

Doc Type	Location	Naming
ADRs	docs/adr/	ADR-XXX-{description}.md
Runbooks	docs/runbooks/	{operation}-runbook.md
Architecture	docs/architecture/	{system}-architecture.md
KT Docs	docs/	KT-{{TICKET_PREFIX}}-XXX-{topic}.md
Technical Docs	docs/agent-outputs/technical-docs/	{{TICKET_PREFIX}}-XXX-{description}.md

Documentation Checklist

Before publishing any documentation:

• Clear, descriptive title
• Proper heading hierarchy (H1 > H2 > H3)
• Code blocks with language tags
• Links to related documents
• Author and date included
• No sensitive data (secrets, passwords)
• Spell-checked
• Markdown lint passes