Confluence Documentation Creator

Purpose

Creates comprehensive Confluence documentation at each orchestration phase with full linking to Jira issues and PRs.

Input Context

confluence_space: "PROJECT"
jira_issue_key: "PROJ-123"
jira_issue_url: "https://..."
github_pr_url: "https://..."
github_pr_number: 42
phase: "PLAN|CODE|TEST|DOCUMENT"
feature_name: "Feature Name"
version: "1.2.0"
project_root: "/path/to/project"

Document Templates by Phase

1. Technical Design Document (PLAN Phase)

Sections:

• Executive Summary
• Problem Statement (Current/Desired/Success Criteria)
• Architecture Design (Overview, Components, Data Models, API Specs, DB Schema)
• Security Considerations (Auth, Data Protection, Input Validation, Audit Logging)
• Performance Considerations (Load, Caching, Database, Monitoring)
• Integration Points (External/Internal)
• Deployment Architecture (Requirements, Config, Rollout)
• Risk Assessment
• Open Questions
• References & Next Steps

2. Implementation Notes (CODE Phase)

Sections:

• Implementation Overview
• Code Architecture (Directory Structure, Key Files, Architectural Decisions)
• Key Abstractions & Patterns
• Integration Points (Internal/External)
• Configuration (Env Variables, Feature Flags)
• Database Changes (Migrations, Rollback)
• Error Handling (Types, Retry Logic)
• Performance Optimizations (Caching, DB, Code)
• Testing Considerations (Coverage, Utilities)
• Known Limitations
• Code Review Notes
• Implementation Checklist

3. Test Plan & Results (TEST Phase)

Sections:

• Test Strategy (Pyramid, Types)
• Unit Test Results (Coverage, Critical Cases)
• Integration Test Results (Scenarios, DB)
• E2E Test Results (User Journeys, Browser Compatibility)
• Performance Test Results (Load, Stress, DB Performance)
• Edge Cases & Boundary Testing
• Security Testing (Auth, Authorization, Input, Data Protection)
• Accessibility Testing (WCAG 2.1 AA)
• Regression Testing
• Test Failures & Issues
• Test Environment
• Coverage Gaps
• Sign-Off (Approvals)

4. Runbook/Operations Guide (DOCUMENT Phase)

Sections:

• Service Overview & Quick Links
• Deployment Guide (Prerequisites, Process, Strategies)
• Monitoring & Alerts (Key Metrics, Alert Rules, Dashboards)
• Troubleshooting Guide (Common Issues, Diagnosis, Resolution)
• Rollback Procedures
• Configuration Management (Env Vars, Secrets, Feature Flags)
• Scaling Guide (Horizontal/Vertical)
• Maintenance Procedures (Routine, Database)
• Disaster Recovery (Backup, Recovery, RTO/RPO)
• Security Considerations (Access Control, Best Practices)
• Runbook Changelog
• Contact Information & Escalation

5. Release Notes (CHANGELOG)

Sections:

• What's New (Features with description, benefits, usage)
• Improvements
• Bug Fixes
• Breaking Changes
• Migration Guide (Schema, Config, Code)
• Deprecation Notices
• Known Issues
• Upgrade Instructions (Docker, Kubernetes, npm)
• Performance Improvements (Benchmarks)
• Security Updates (CVEs)
• Dependencies Updated
• Documentation Updates
• Contributors & Rollback Instructions
• Support & References

Page Hierarchy

{Project Space}/
├── Features/
│   └── {ISSUE-KEY} - {Feature Name}          [Parent]
│       ├── Technical Design                   [Child]
│       ├── Implementation Notes                [Child]
│       ├── Test Plan & Results                 [Child]
│       └── Runbook                            [Child]
├── API Documentation/
└── Release Notes/

Implementation Workflow

1. Find Confluence Space

Search for project space by key or name. Ask user if not found.

2. Create Page Hierarchy

• Create parent page: {ISSUE-KEY} - {Feature Name}
• Create child pages for phase documents
• Use consistent naming: {ISSUE-KEY} - {Document Type}: {Feature Name}

3. Link Everything

• Add Confluence page links to Jira issue (comment)
• Add Confluence page links to GitHub PR (comment)
• Include Jira/PR links in Confluence pages

4. Content Discovery

Auto-populate documentation by analyzing codebase:

• Extract architecture from service/component files
• Parse TypeScript interfaces for data models
• Extract API specs from OpenAPI or route files
• Read test coverage from coverage reports
• Parse test results from test output

5. Error Handling

• Retry network failures (3 attempts, exponential backoff)
• Ask user for missing information
• Handle permission errors gracefully
• Log errors without failing silently

Key Capabilities

• Template Rendering: Convert markdown templates to Confluence storage format
• Auto-population: Extract data from codebase to fill templates
• Jira Integration: Comment on issues with Confluence page links
• GitHub Integration: Comment on PRs with documentation links
• Error Resilience: Retry failed requests and handle missing data
• Page Management: Create, update, organize documentation pages
• Cross-linking: Connect related pages, issues, and PRs

Best Practices

1. Link everything together (Confluence ↔ Jira ↔ GitHub)
2. Use consistent naming conventions
3. Create page hierarchy for organization
4. Auto-populate with real codebase data
5. Handle errors gracefully with retries
6. Update existing pages instead of duplicating
7. Include actual code snippets and metrics

Success Output

✅ Confluence Documentation Created

**Technical Design Document**
- URL: https://confluence.example.com/...
- Status: Published

**Links Created:**
- ✅ Jira comment added
- ✅ GitHub PR comment added

**Next Steps:**
1. Review document
2. Proceed to next phase

See Also

• Jira Orchestration: jira-orchestrator:jira-orchestration
• PR Workflow: jira-orchestrator:pr-workflow
• Technical Design ADRs: Referenced in documents