/confluence-docs

name: confluence-docs
description: Documentation templates for ADRs, runbooks, and architecture docs. Use when creating architectural decision records, operational runbooks, or technical documentation.
allowed-tools: Read, Write, Edit, Grep, Glob

Confluence Documentation Skill

Purpose

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

When This Skill Applies

Invoke this skill when:

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

Existing ADRs (Reference)

| ADR | Location | Topic | | ------- | ---------------------------------------------------------- | ------------------------- | | ADR-002 | `docs/adr/ADR-002-constants-unification.md` | Constants organization | | ADR-003 | `docs/adr/ADR-003-dependency-upgrade-typescript-fixes.md` | Dependency upgrades | | ADR-004 | `docs/adr/ADR-004-server-component-data-access-pattern.md` | Server component patterns | | ADR-005 | `docs/adr/ADR-005-ci-infrastructure-services.md` | CI infrastructure | | ADR-006 | `docs/adr/ADR-006-bonus-pdf-private-bucket-security.md` | Security patterns | | ADR-007 | `docs/adr/ADR-007-rendertrust-marketing-pages.md` | Marketing architecture |

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]

\`\`\`bash

# 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

### Component 2: [Name]

...

## 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.ts`
  - 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 (`yarn lint:md`)