Confluence Expert

Atlassian Confluence Expert

Master-level expertise in Confluence space management, documentation architecture, content creation, macros, templates, and collaborative knowledge management.

Atlassian MCP Integration

Primary Tool: Atlassian Remote MCP server (bundled .mcp.json, server key atlassian). Tools are camelCase and surface as mcp__atlassian__<toolName>. Canonical tool list: project-management/references/atlassian-mcp-tools.md. Never invent tool names — if a capability isn't in that list, it is not available via MCP.

Key Operations (obtain cloudId once via mcp__atlassian__getAccessibleAtlassianResources):

// List spaces (space CREATION is not available via MCP — see below)
mcp__atlassian__getConfluenceSpaces (cloudId)

// Create a page under a parent — body must be storage-format XHTML or ADF, never wiki markup
mcp__atlassian__createConfluencePage (cloudId, space, title="Sprint 42 Notes", parent page id, body="<p>Meeting notes in storage-format XHTML</p>")

// Update an existing page (fetch current version with getConfluencePage, then supply version + 1)
mcp__atlassian__updateConfluencePage (cloudId, pageId="789012", version=5, body="<p>Updated content</p>")

// Read a page (body + current version)
mcp__atlassian__getConfluencePage (cloudId, pageId="789012")

// Search with CQL
mcp__atlassian__searchConfluenceUsingCql (cloudId, cql='space = "TEAM" AND label = "meeting-notes" ORDER BY lastModified DESC')

// Retrieve child pages for hierarchy inspection
mcp__atlassian__getConfluencePageDescendants (cloudId, pageId="123456")

// Comments
mcp__atlassian__getConfluencePageFooterComments / mcp__atlassian__createConfluenceFooterComment (cloudId, pageId)

Not available via MCP — use the web UI or REST API instead:

• Create/delete a space → Confluence UI Spaces > Create space or POST /wiki/api/v2/spaces
• Delete a page → Confluence UI or DELETE /wiki/api/v2/pages/{id}
• Apply labels → Confluence UI or /wiki/rest/api/content/{id}/label
• Space permissions, templates/blueprints as first-class objects → Confluence space settings UI

Integration Points:

• Create documentation for Senior PM projects
• Support Scrum Master with ceremony templates
• Link to Jira issues for Jira Expert
• Provide templates for Template Creator

See also: references/macro-cheat-sheet.md for storage-format macro syntax, references/templates.md for the template library, references/space-architecture-patterns.md for space structure and permission patterns.

Workflows

Space Creation

Space creation is not available via MCP — create the space in the Confluence UI (Spaces > Create space) or via REST (POST /wiki/api/v2/spaces). The page tree inside it CAN be built via MCP (mcp__atlassian__createConfluencePage).

0. Generate the recommended hierarchy from a team description:

   python3 scripts/space_structure_generator.py team_info.json --format json

Input: JSON with team name, size, type, projects. Consume the output: use the emitted page tree as the creation plan for step 5 — one mcp__atlassian__createConfluencePage call per node, passing the parent page id to nest children. 1. Determine space type (Team, Project, Knowledge Base, Personal) 2. Create space with clear name and description (web UI / REST) 3. Set space homepage with overview 4. Configure space permissions:

• View, Edit, Create, Delete
• Admin privileges

5. Create initial page tree structure 6. Add space shortcuts for navigation 7. Verify: Navigate to the space URL and confirm the homepage loads; check that a non-admin test user sees the correct permission level 8. HANDOFF TO: Teams for content population

Page Architecture

Best Practices:

• Use page hierarchy (parent-child relationships)
• Maximum 3 levels deep for navigation
• Consistent naming conventions
• Date-stamp meeting notes

Recommended Structure:

Space Home
├── Overview & Getting Started
├── Team Information
│   ├── Team Members & Roles
│   ├── Communication Channels
│   └── Working Agreements
├── Projects
│   ├── Project A
│   │   ├── Overview
│   │   ├── Requirements
│   │   └── Meeting Notes
│   └── Project B
├── Processes & Workflows
├── Meeting Notes (Archive)
└── Resources & References

Template Creation

1. Identify repeatable content pattern 2. Create page with structure and placeholders 3. Add instructions in placeholders 4. Format with appropriate macros 5. Save as template 6. Share with space or make global 7. Verify: Create a test page from the template and confirm all placeholders render correctly before sharing with the team 8. USE: References for advanced template patterns

Documentation Strategy

1. Assess current documentation state 2. Define documentation goals and audience 3. Organize content taxonomy and structure 4. Create templates and guidelines 5. Migrate existing documentation 6. Train teams on best practices 7. Monitor usage and adoption 8. REPORT TO: Senior PM on documentation health

Knowledge Base Management

Run a content health audit before any restructure or governance review:

python3 scripts/content_audit_analyzer.py pages.json --format json

Input: a JSON page inventory (title, last_modified, view_count, author, labels, word_count) — build it by exporting page metadata via mcp__atlassian__getPagesInConfluenceSpace / mcp__atlassian__searchConfluenceUsingCql. Consume the output: the stale/orphaned/low-engagement findings become the archive list (label + move via UI, since label tools aren't on the MCP) and the update backlog for the quality standards below.

Article Types:

• How-to guides
• Troubleshooting docs
• FAQs
• Reference documentation
• Process documentation

Quality Standards:

• Clear title and description
• Structured with headings
• Updated date visible
• Owner identified
• Reviewed quarterly

Essential Macros

Syntax note: The {macro} shorthand below is legacy wiki-markup notation, shown for readability only. Confluence Cloud pages created via MCP (createConfluencePage / updateConfluencePage) require storage format (XHTML) — e.g. {info} is really <ac:structured-macro ac:name="info"><ac:rich-text-body>...</ac:rich-text-body></ac:structured-macro>. For the storage-format syntax of every macro listed here, see references/macro-cheat-sheet.md; for ready-made storage-format page bodies, run the atlassian-templates scaffolder (python3 ../atlassian-templates/scripts/template_scaffolder.py meeting-notes).

Content Macros

Info, Note, Warning, Tip:

{info}
Important information here
{info}

Expand:

{expand:title=Click to expand}
Hidden content here
{expand}

Table of Contents:

{toc:maxLevel=3}

Excerpt & Excerpt Include:

{excerpt}
Reusable content
{excerpt}

{excerpt-include:Page Name}

Dynamic Content

Jira Issues:

{jira:JQL=project = PROJ AND status = "In Progress"}

Jira Chart:

{jirachart:type=pie|jql=project = PROJ|statType=statuses}

Recently Updated:

{recently-updated:spaces=@all|max=10}

Content by Label:

{contentbylabel:label=meeting-notes|maxResults=20}

Collaboration Macros

Status:

{status:colour=Green|title=Approved}

Task List:

{tasks}
- [ ] Task 1
- [x] Task 2 completed
{tasks}

User Mention:

@username

Date:

{date:format=dd MMM yyyy}

Page Layouts & Formatting

Two-Column Layout:

{section}
{column:width=50%}
Left content
{column}
{column:width=50%}
Right content
{column}
{section}

Panel:

{panel:title=Panel Title|borderColor=#ccc}
Panel content
{panel}

Code Block:

{code:javascript}
const example = "code here";
{code}

Templates Library

Full template library with complete markup: see references/templates.md. Key templates summarised below.

Space Permissions

Permission patterns by space type: see references/space-architecture-patterns.md. Note: space permissions are configured in the Confluence UI (Space settings > Permissions) — not via MCP.

Permission Schemes

Public Space:

• All users: View
• Team members: Edit, Create
• Space admins: Admin

Team Space:

• Team members: View, Edit, Create
• Team leads: Admin
• Others: No access

Project Space:

• Stakeholders: View
• Project team: Edit, Create
• PM: Admin

Content Governance

Review Cycles:

• Critical docs: Monthly
• Standard docs: Quarterly
• Archive docs: Annually

Archiving Strategy:

• Move outdated content to Archive space
• Label with "archived" and date
• Maintain for 2 years, then delete
• Keep audit trail

Content Quality Checklist:

• [ ] Clear, descriptive title
• [ ] Owner/author identified
• [ ] Last updated date visible
• [ ] Appropriate labels applied
• [ ] Links functional
• [ ] Formatting consistent
• [ ] No sensitive data exposed

Decision Framework

When to Escalate to Atlassian Admin:

• Need org-wide template
• Require cross-space permissions
• Blueprint configuration
• Global automation rules
• Space export/import

When to Collaborate with Jira Expert:

• Embed Jira queries and charts
• Link pages to Jira issues
• Create Jira-based reports
• Sync documentation with tickets

When to Support Scrum Master:

• Sprint documentation templates
• Retrospective pages
• Team working agreements
• Process documentation

When to Support Senior PM:

• Executive report pages
• Portfolio documentation
• Stakeholder communication
• Strategic planning docs

Handoff Protocols

FROM Senior PM:

• Documentation requirements
• Space structure needs
• Template requirements
• Knowledge management strategy

TO Senior PM:

• Documentation coverage reports
• Content usage analytics
• Knowledge gaps identified
• Template adoption metrics

FROM Scrum Master:

• Sprint ceremony templates
• Team documentation needs
• Meeting notes structure
• Retrospective format

TO Scrum Master:

• Configured templates
• Space for team docs
• Training on best practices
• Documentation guidelines

WITH Jira Expert:

• Jira-Confluence linking
• Embedded Jira reports
• Issue-to-page connections
• Cross-tool workflow

Best Practices

Organization:

• Consistent naming conventions
• Meaningful labels
• Logical page hierarchy
• Related pages linked
• Clear navigation

Maintenance:

• Regular content audits
• Remove duplication
• Update outdated information
• Archive obsolete content
• Monitor page analytics

Analytics & Metrics

Usage Metrics:

• Page views per space
• Most visited pages
• Search queries
• Contributor activity
• Orphaned pages

Health Indicators:

• Pages without recent updates
• Pages without owners
• Duplicate content
• Broken links
• Empty spaces

Related Skills

• Jira Expert (project-management/jira-expert/) — Jira issue macros and linking complement Confluence docs
• Atlassian Templates (project-management/atlassian-templates/) — Template patterns for Confluence content creation

Confluence Macro Cheat Sheet

Overview

Quick reference for the most commonly used Confluence macros. Each entry includes the macro name, storage format syntax, primary use case, and practical tips.

Navigation & Structure Macros

Table of Contents

• Purpose: Auto-generate a linked table of contents from page headings
• Syntax: <ac:structured-macro ac:name="toc" />
• Parameters: maxLevel (1-6), minLevel (1-6), style (disc, circle, square, none), type (list, flat)
• Use case: Long documentation pages, meeting notes, specifications
• Tip: Set maxLevel="3" to avoid overly deep TOC entries

Children Display

• Purpose: List child pages of the current page
• Syntax: <ac:structured-macro ac:name="children" />
• Parameters: depth (1-999), sort (title, creation, modified), style (h2-h6), all (true/false)
• Use case: Parent hub pages, project homepages, documentation indexes
• Tip: Use depth="1" for clean navigation, all="true" for deep hierarchies

Include Page

• Purpose: Embed content from another page inline
• Syntax: <ac:structured-macro ac:name="include"><ac:parameter ac:name=""><ac:link><ri:page ri:content-title="Page Name" /></ac:link></ac:parameter></ac:structured-macro>
• Use case: Reusable content blocks (headers, footers, disclaimers)
• Tip: Changes to the source page are reflected everywhere it is included

Page Properties

• Purpose: Define structured metadata on a page (key-value pairs)
• Syntax: <ac:structured-macro ac:name="details"> with table inside
• Use case: Project metadata, status tracking, structured page data
• Tip: Combine with Page Properties Report macro to create dashboards

Page Properties Report

• Purpose: Display a table of Page Properties from child pages
• Syntax: <ac:structured-macro ac:name="detailssummary" />
• Parameters: cql (CQL filter), labels (filter by label)
• Use case: Project dashboards, status rollups, portfolio views
• Tip: Use labels to scope the report to relevant pages only

Visual & Formatting Macros

Info Panel

• Purpose: Blue information callout box
• Syntax: <ac:structured-macro ac:name="info"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>
• Use case: Helpful notes, additional context, best practices

Warning Panel

• Purpose: Yellow warning callout box
• Syntax: <ac:structured-macro ac:name="warning"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>
• Use case: Important caveats, deprecation notices, breaking changes

Note Panel

• Purpose: Yellow note callout box
• Syntax: <ac:structured-macro ac:name="note"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>
• Use case: Reminders, action items, things to watch

Tip Panel

• Purpose: Green tip callout box
• Syntax: <ac:structured-macro ac:name="tip"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>
• Use case: Pro tips, shortcuts, recommended approaches

Expand

• Purpose: Collapsible content section (click to expand)
• Syntax: <ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">Click to expand</ac:parameter><ac:rich-text-body>Hidden content</ac:rich-text-body></ac:structured-macro>
• Use case: Long sections, FAQs, detailed explanations, optional reading
• Tip: Use for content that not all readers need

Status

• Purpose: Colored status lozenge (inline label)
• Syntax: <ac:structured-macro ac:name="status"><ac:parameter ac:name="colour">Green</ac:parameter><ac:parameter ac:name="title">DONE</ac:parameter></ac:structured-macro>
• Colors: Grey, Red, Yellow, Green, Blue
• Use case: Task status, review state, approval status
• Tip: Standardize status values across your team (e.g., TODO, IN PROGRESS, DONE)

Integration Macros

Jira Issues

• Purpose: Display Jira issues or JQL query results
• Syntax: <ac:structured-macro ac:name="jira"><ac:parameter ac:name="jqlQuery">project = PROJ AND status = Open</ac:parameter></ac:structured-macro>
• Parameters: jqlQuery, columns (key, summary, status, assignee, etc.), count (true/false), serverId
• Use case: Sprint boards in documentation, requirement traceability, release notes
• Tip: Use columns parameter to show only relevant fields

Roadmap Planner

• Purpose: Visual timeline/Gantt view of items
• Syntax: Available via macro browser (Roadmap Planner)
• Use case: Project timelines, release planning, milestone tracking
• Tip: Link roadmap items to Jira epics for automatic status updates

Chart Macro

• Purpose: Create charts from table data on the page
• Syntax: <ac:structured-macro ac:name="chart"><ac:parameter ac:name="type">pie</ac:parameter><ac:rich-text-body>Table data</ac:rich-text-body></ac:structured-macro>
• Types: pie, bar, line, area, scatter, timeSeries
• Use case: Status distribution, metrics dashboards, trend visualization
• Tip: Place a Confluence table inside the macro body as data source

Content Reuse Macros

Excerpt

• Purpose: Mark a section of content for reuse via Excerpt Include
• Syntax: <ac:structured-macro ac:name="excerpt"><ac:rich-text-body>Reusable content</ac:rich-text-body></ac:structured-macro>
• Use case: Define canonical content blocks (product descriptions, team info)

Excerpt Include

• Purpose: Display an Excerpt from another page
• Syntax: <ac:structured-macro ac:name="excerpt-include"><ac:parameter ac:name=""><ac:link><ri:page ri:content-title="Source Page" /></ac:link></ac:parameter></ac:structured-macro>
• Use case: Embed product descriptions, standard disclaimers, shared definitions

Advanced Macros

Code Block

• Purpose: Display formatted code with syntax highlighting
• Syntax: <ac:structured-macro ac:name="code"><ac:parameter ac:name="language">python</ac:parameter><ac:plain-text-body>code here</ac:plain-text-body></ac:structured-macro>
• Languages: java, python, javascript, sql, bash, xml, json, and many more
• Use case: API documentation, configuration examples, code snippets

Anchor

• Purpose: Create a named anchor point for deep linking
• Syntax: <ac:structured-macro ac:name="anchor"><ac:parameter ac:name="">anchor-name</ac:parameter></ac:structured-macro>
• Use case: Link directly to specific sections within long pages
• Tip: Use with TOC macro for custom navigation

Recently Updated

• Purpose: Show recently modified pages in a space
• Syntax: <ac:structured-macro ac:name="recently-updated" />
• Parameters: spaces, labels, types, max
• Use case: Team dashboards, space homepages, activity feeds

Macro Selection Guide

Confluence Space Architecture Patterns

Overview

Well-organized Confluence spaces dramatically improve information discoverability and team productivity. This guide covers proven space organization patterns, page hierarchy best practices, and governance strategies.

Space Organization Patterns

Pattern 1: By Team

Each team or department gets its own space.

Structure:

Engineering Space (ENG)
Product Space (PROD)
Marketing Space (MKT)
Design Space (DES)
Support Space (SUP)

Pros:

• Clear ownership and permissions
• Teams control their own content
• Natural permission boundaries
• Easy to find team-specific content

Cons:

• Cross-team content duplication
• Silos between departments
• Hard to find project-spanning information
• Inconsistent practices across spaces

Best for: Organizations with stable teams and clear departmental boundaries

Pattern 2: By Project

Each major project or product gets its own space.

Structure:

Project Alpha Space (ALPHA)
Project Beta Space (BETA)
Platform Infrastructure Space (PLAT)
Internal Tools Space (TOOLS)

Pros:

• All project context in one place
• Easy onboarding for project members
• Clean archival when project completes
• Natural lifecycle management

Cons:

• Team knowledge scattered across spaces
• Permission management per project
• Space proliferation over time
• Ongoing vs project work separation unclear

Best for: Project-based organizations, agencies, consulting firms

Pattern 3: By Domain (Hybrid)

Combine functional spaces with cross-cutting project spaces.

Structure:

Company Wiki (WIKI) - Shared knowledge
Engineering Standards (ENG) - Team practices
Product Specs (PROD) - Requirements and roadmap
Project Alpha (ALPHA) - Cross-team project
Project Beta (BETA) - Cross-team project
Archive (ARCH) - Completed projects

Pros:

• Balances team and project needs
• Shared knowledge has a home
• Clear archival path
• Scales with organization growth

Cons:

• More complex to set up initially
• Requires governance to maintain
• Some ambiguity about where content belongs

Best for: Growing organizations, 50-500 people, multiple concurrent projects

Page Hierarchy Best Practices

Recommended Depth

• Maximum 4 levels deep - Deeper hierarchies become hard to navigate
• 3 levels ideal for most content types
• Use flat structures with labels for categorization beyond 4 levels

Standard Page Hierarchy

Space Home (overview, quick links, recent updates)
├── Getting Started
│   ├── Onboarding Guide
│   ├── Tool Setup
│   └── Key Contacts
├── Projects
│   ├── Project Alpha
│   │   ├── Requirements
│   │   ├── Design
│   │   └── Meeting Notes
│   └── Project Beta
├── Processes
│   ├── Development Workflow
│   ├── Release Process
│   └── On-Call Runbook
├── References
│   ├── Architecture Decisions
│   ├── API Documentation
│   └── Glossary
└── Archive
    ├── 2025 Projects
    └── Deprecated Processes

Page Naming Conventions

• Use clear, descriptive titles (not abbreviations)
• Include date for time-sensitive content: "2025-Q1 Planning"
• Prefix meeting notes with date: "2025-03-15 Sprint Review"
• Use consistent casing (Title Case or Sentence case, not both)
• Avoid special characters that break URLs

Space Homepage Design

Every space homepage should include: 1. Space purpose - One paragraph describing what this space is for 2. Quick links - 5-7 most accessed pages 3. Recent updates - Recently Updated macro filtered to this space 4. Getting started - Link to onboarding content for new members 5. Contact info - Space owner, key contributors

Labeling Taxonomy

Label Categories

• Content type: meeting-notes, decision, specification, runbook, retrospective
• Status: draft, in-review, approved, deprecated, archived
• Team: team-engineering, team-product, team-design
• Project: project-alpha, project-beta
• Priority: high-priority, p1, critical

Labeling Best Practices

• Use lowercase, hyphenated labels (no spaces or camelCase)
• Define a standard label vocabulary and document it
• Use labels for cross-space categorization
• Combine labels with CQL for powerful search and reporting
• Audit labels quarterly to remove unused or inconsistent labels
• Limit to 3-5 labels per page (over-labeling reduces value)

CQL Examples for Label-Based Queries

# All meeting notes in a space
type = page AND space = "ENG" AND label = "meeting-notes"

# All approved specifications
type = page AND label = "specification" AND label = "approved"

# Recent decisions across all spaces
type = page AND label = "decision" AND lastModified > now("-30d")

Cross-Space Linking

When to Link vs Duplicate

• Link when content has a single source of truth
• Duplicate (Include Page macro) when content must appear in multiple contexts
• Excerpt Include when only a portion of a page is needed elsewhere

Linking Best Practices

• Use full page titles in links for clarity
• Add context around links ("See the [Architecture Decision Record] for rationale")
• Avoid orphan pages - every page should be reachable from space navigation
• Use the Recently Updated macro on hub pages for activity visibility
• Create "Related Pages" sections at the bottom of content pages

Archive Strategy

When to Archive

• Project completed more than 90 days ago
• Process or document officially deprecated
• Content not updated in 12+ months
• Replaced by newer content

Archive Process

1. Add archived label to the page 2. Move to Archive section within the space (or dedicated Archive space) 3. Add a note at the top: "This page is archived as of [date]. See [replacement] for current information." 4. Update any incoming links to point to current content 5. Do NOT delete - archived content has historical value

Archive Space Pattern

• Create a dedicated Archive space for completed projects
• Move entire project page trees to Archive space on completion
• Set Archive space to read-only permissions
• Review Archive space annually for content that can be deleted

Permission Inheritance Patterns

Pattern 1: Open by Default

• All spaces readable by all employees
• Edit restricted to space members
• Admin restricted to space owners
• Best for: Transparency-focused organizations

Pattern 2: Restricted by Default

• Spaces accessible only to specific groups
• Request access via space admin
• Best for: Regulated industries, confidential projects

Pattern 3: Tiered Access

• Public tier: Company wiki, shared processes
• Team tier: Team-specific spaces with team access
• Restricted tier: HR, finance, legal with limited access
• Best for: Most organizations (balanced approach)

Permission Tips

• Use Confluence groups, not individual users, for permissions
• Align groups with LDAP/SSO groups where possible
• Audit permissions quarterly
• Document permission model on the space homepage
• Use page-level restrictions sparingly (breaks inheritance, hard to audit)

Scaling Considerations

< 50 People

• 3-5 spaces total
• Simple by-team pattern
• Light governance

50-200 People

• 10-20 spaces
• Hybrid pattern (team + project)
• Formal labeling taxonomy
• Quarterly content reviews

200+ People

• 20-50+ spaces
• Full domain pattern with governance
• Space owners and content stewards
• Automated archival policies
• Regular information architecture reviews

Confluence Page Templates

Meeting Notes Template

# [Meeting Title] - [Date]

**Date:** [YYYY-MM-DD]
**Time:** [HH:MM - HH:MM]
**Location:** [Room/Video link]
**Attendees:** @[Name1], @[Name2], @[Name3]
**Note Taker:** @[Name]

## Agenda
1. [Topic 1]
2. [Topic 2]
3. [Topic 3]

## Discussion

### [Topic 1]
**Summary:**
[Key points discussed]

**Decisions:**
- [Decision 1]
- [Decision 2]

**Action Items:**
- [ ] [Action] - @[Owner] - [Due Date]
- [ ] [Action] - @[Owner] - [Due Date]

### [Topic 2]
**Summary:**
[Key points discussed]

**Decisions:**
- [Decision 1]

**Action Items:**
- [ ] [Action] - @[Owner] - [Due Date]

## Parking Lot
- [Item to discuss later]
- [Future topic]

## Next Meeting
**Date:** [YYYY-MM-DD]
**Agenda Topics:**
- [Topic 1]
- [Topic 2]

---

Decision Log Template

# [Decision Title]

| Field | Value |
|-------|-------|
| **Status** | 🟢 Accepted / 🟡 Proposed / 🔴 Deprecated |
| **Date** | [YYYY-MM-DD] |
| **Deciders** | @[Name1], @[Name2] |
| **Stakeholders** | @[Name3], @[Name4] |
| **Related Decisions** | [Link to related decisions] |

## Context and Problem Statement
[Describe the context and problem that requires a decision. 2-3 paragraphs explaining:
- What situation led to this decision?
- What problem are we trying to solve?
- What constraints exist?]

## Decision
[Clearly state the decision made in 1-2 sentences]

### Details
[Provide additional details about the decision:
- What exactly will we do?
- How will it be implemented?
- What timeline?]

## Rationale
[Explain why this decision was made:
- What were the key factors?
- What evidence supports this?
- Why is this the best choice?]

## Consequences

### Positive Consequences
- ✅ [Benefit 1]
- ✅ [Benefit 2]
- ✅ [Benefit 3]

### Negative Consequences / Trade-offs
- ⚠️ [Trade-off 1]
- ⚠️ [Trade-off 2]

### Risks
- 🔴 [Risk 1] - Mitigation: [How we'll handle it]
- 🟡 [Risk 2] - Mitigation: [How we'll handle it]

## Alternatives Considered

### Alternative 1: [Name]
**Description:** [What is this alternative?]

**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

**Why Not Chosen:** [Reason]

### Alternative 2: [Name]
[Same structure as above]

## Implementation Plan
1. [Step 1] - @[Owner] - [Date]
2. [Step 2] - @[Owner] - [Date]
3. [Step 3] - @[Owner] - [Date]

## Success Metrics
- [Metric 1]: [Target]
- [Metric 2]: [Target]

## Review Date
**Next Review:** [YYYY-MM-DD]
**Review Notes:** [Link to review page]

## References
- [Link 1]
- [Link 2]
- [Link 3]

---
*Updated: [Date] by @[Name]*

---

Technical Specification Template

# [Feature/Component Name] Technical Specification

| Field | Value |
|-------|-------|
| **Status** | 🟡 Draft / 🟢 Approved / 🔴 Archived |
| **Author** | @[Name] |
| **Reviewers** | @[Name1], @[Name2] |
| **Date Created** | [YYYY-MM-DD] |
| **Last Updated** | [YYYY-MM-DD] |
| **JIRA Epic** | [ABC-123](link) |

## Overview
[1-2 paragraph summary of what this spec covers and why it matters]

## Goals and Non-Goals

### Goals
- [Goal 1]
- [Goal 2]
- [Goal 3]

### Non-Goals (Out of Scope)
- [Non-goal 1]
- [Non-goal 2]

## Background
[Context needed to understand this spec:
- What problem are we solving?
- What's the current state?
- Why now?]

## High-Level Design

### Architecture Diagram
[Insert diagram here]

### System Components
1. **[Component 1 Name]**
   - Purpose: [What it does]
   - Technology: [What it uses]
   - Interfaces: [How it connects]

2. **[Component 2 Name]**
   - Purpose: [What it does]
   - Technology: [What it uses]
   - Interfaces: [How it connects]

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

## Detailed Design

### Component 1: [Name]
**Purpose:** [Detailed purpose]

**Responsibilities:**
- [Responsibility 1]
- [Responsibility 2]

**API/Interface:**

[API spec or interface definition]

**Data Model:**

[Schema or data structure]

**Key Algorithms/Logic:**
[Describe any complex logic]

### Component 2: [Name]
[Same structure as Component 1]

## Database Schema

### Table: [table_name]
| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | UUID | PRIMARY KEY | Unique identifier |
| name | VARCHAR(255) | NOT NULL | Entity name |
| created_at | TIMESTAMP | NOT NULL | Creation timestamp |

### Indexes
- `idx_name` on `name` - For fast lookups
- `idx_created` on `created_at` - For temporal queries

## API Specification

### Endpoint: [Method] /api/path
**Purpose:** [What this endpoint does]

**Request:**

{ "param1": "value", "param2": 123 }

**Response:**

{ "result": "success", "data": {} }

**Error Handling:**
- 400: [Reason]
- 404: [Reason]
- 500: [Reason]

## Security Considerations
- [Security consideration 1]
- [Security consideration 2]
- [Authentication/Authorization approach]
- [Data encryption requirements]

## Performance Considerations
- [Expected load/throughput]
- [Scalability approach]
- [Caching strategy]
- [Performance targets]

## Testing Strategy

### Unit Tests
- [Test area 1]
- [Test area 2]

### Integration Tests
- [Test scenario 1]
- [Test scenario 2]

### Performance Tests
- [Load test plan]
- [Performance benchmarks]

## Deployment Plan
1. [Deployment step 1]
2. [Deployment step 2]
3. [Deployment step 3]

### Rollback Plan
[How to revert if issues occur]

## Monitoring and Alerting
- [Metric 1] - Alert threshold: [Value]
- [Metric 2] - Alert threshold: [Value]
- [Log tracking]

## Migration Plan (if applicable)
[How to migrate from current system]

## Dependencies
- [Dependency 1] - Why needed
- [Dependency 2] - Why needed

## Open Questions
- [ ] [Question 1] - @[Owner]
- [ ] [Question 2] - @[Owner]

## Future Considerations
- [Future enhancement 1]
- [Future enhancement 2]

## References
- [Link to related specs]
- [Link to design docs]
- [Link to JIRA epics]

---
*For questions, contact @[Author]*

---

How-To Guide Template

# How to [Task Name]

## Overview
[1-2 sentences explaining what this guide covers and who it's for]

**Estimated Time:** [X minutes]
**Difficulty:** [Beginner/Intermediate/Advanced]

## Prerequisites
Before you begin, ensure you have:
- [ ] [Prerequisite 1]
- [ ] [Prerequisite 2]
- [ ] [Prerequisite 3]

## Quick Summary (TL;DR)
[One paragraph with the essence of the guide for those who just need a reminder]

## Step-by-Step Instructions

### Step 1: [Action]
[Detailed description of what to do]

**Commands/Code:**

command here

**Expected Result:**
[What you should see if it worked]

**Screenshot:**
[Add screenshot if helpful]

### Step 2: [Action]
[Detailed description]

**Tips:**
- 💡 [Helpful tip]
- ⚠️ [Warning about common mistake]

### Step 3: [Action]
[Continue pattern...]

## Verification
To verify everything worked:
1. [Check 1]
2. [Check 2]

## Troubleshooting

### Problem: [Common issue]
**Symptoms:** [What you see]
**Cause:** [Why it happens]
**Solution:**
1. [Fix step 1]
2. [Fix step 2]

### Problem: [Another issue]
[Same structure as above]

## Best Practices
- [Best practice 1]
- [Best practice 2]
- [Best practice 3]

## Related Guides
- [Link to related guide 1]
- [Link to related guide 2]

## Need Help?
- Questions? Ask in #[channel]
- Issues? Create ticket in [JIRA project]
- Contact: @[Expert name]

---
*Last updated: [Date] by @[Name]*

---

Requirements Document Template

# [Feature/Project Name] Requirements

| Field | Value |
|-------|-------|
| **Status** | 🟡 Draft / 🟢 Approved / 🔵 In Progress / ✅ Complete |
| **Product Owner** | @[Name] |
| **Stakeholders** | @[Name1], @[Name2] |
| **Target Release** | [Release version] |
| **JIRA Epic** | [ABC-123](link) |
| **Created** | [YYYY-MM-DD] |
| **Last Updated** | [YYYY-MM-DD] |

## Executive Summary
[2-3 sentences describing the feature and its business value]

## Business Goals
- [Goal 1]: [Metric]
- [Goal 2]: [Metric]
- [Goal 3]: [Metric]

## User Stories

### Story 1: [Title]
**As a** [user type]
**I want** [goal]
**So that** [benefit]

**Acceptance Criteria:**
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

**Priority:** [High/Medium/Low]
**Effort:** [Story points]

### Story 2: [Title]
[Same structure as Story 1]

## Functional Requirements

### FR-001: [Requirement Title]
**Description:** [What the system must do]

**Rationale:** [Why this is needed]

**Acceptance Criteria:**
- [Criterion 1]
- [Criterion 2]

**Priority:** [Must Have / Should Have / Could Have / Won't Have]

### FR-002: [Requirement Title]
[Same structure as FR-001]

## Non-Functional Requirements

### Performance
- [Requirement 1]
- [Requirement 2]

### Security
- [Requirement 1]
- [Requirement 2]

### Scalability
- [Requirement 1]
- [Requirement 2]

### Accessibility
- [Requirement 1]
- [Requirement 2]

## User Experience

### Wireframes
[Insert wireframes or link to Figma]

### User Flow
[Diagram showing user journey]

### UI Requirements
- [UI requirement 1]
- [UI requirement 2]

## Technical Constraints
- [Constraint 1]
- [Constraint 2]
- [Constraint 3]

## Dependencies
| Dependency | Owner | Status | Impact if Blocked |
|------------|-------|--------|-------------------|
| [Dep 1] | @[Name] | 🟢 Ready | [Impact] |
| [Dep 2] | @[Name] | 🟡 In Progress | [Impact] |

## Success Metrics
| Metric | Baseline | Target | How Measured |
|--------|----------|--------|--------------|
| [Metric 1] | [Current] | [Goal] | [Method] |
| [Metric 2] | [Current] | [Goal] | [Method] |

## Risks and Mitigations
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [Risk 1] | High | Medium | [Strategy] |
| [Risk 2] | Medium | Low | [Strategy] |

## Out of Scope
- [Explicitly excluded 1]
- [Explicitly excluded 2]

## Open Questions
- [ ] [Question 1] - @[Owner] - [Due date]
- [ ] [Question 2] - @[Owner] - [Due date]

## Timeline
| Phase | Start Date | End Date | Deliverables |
|-------|-----------|----------|--------------|
| Design | [Date] | [Date] | [Deliverable] |
| Development | [Date] | [Date] | [Deliverable] |
| Testing | [Date] | [Date] | [Deliverable] |
| Launch | [Date] | [Date] | [Deliverable] |

## Approval

### Reviewers
- [ ] Product Owner: @[Name]
- [ ] Engineering Lead: @[Name]
- [ ] Design Lead: @[Name]
- [ ] Stakeholder: @[Name]

**Approved Date:** [YYYY-MM-DD]

## References
- [Market research]
- [User feedback]
- [Technical specs]
- [Related features]

---
*For questions, contact @[Product Owner]*

---

Retrospective Template

# Sprint [N] Retrospective - [Team Name]

**Date:** [YYYY-MM-DD]
**Sprint:** [Sprint N]
**Sprint Dates:** [Start Date] - [End Date]
**Facilitator:** @[Name]
**Participants:** @[Name1], @[Name2], @[Name3]

## Sprint Metrics
- **Velocity:** [X points] (Average: [Y points])
- **Committed:** [X points / N issues]
- **Completed:** [Y points / M issues]
- **Sprint Goal Met:** ✅ Yes / ❌ No

## What Went Well 😊
- [Positive 1]
- [Positive 2]
- [Positive 3]

## What Didn't Go Well 😞
- [Challenge 1]
- [Challenge 2]
- [Challenge 3]

## Action Items from Last Retro
- [✅ / ❌] [Action item 1] - @[Owner]
  - Status: [Done / In Progress / Not Done]
  - Notes: [Update]
- [✅ / ❌] [Action item 2] - @[Owner]
  - Status: [Done / In Progress / Not Done]
  - Notes: [Update]

## Discussion Themes

### Theme 1: [Topic]
**What we discussed:**
[Summary of discussion]

**Root cause:**
[What's really causing this issue?]

**Ideas for improvement:**
- [Idea 1]
- [Idea 2]

### Theme 2: [Topic]
[Same structure as Theme 1]

## Action Items for Next Sprint
| Action | Owner | Due Date | Success Criteria |
|--------|-------|----------|------------------|
| [Action 1] | @[Name] | [Date] | [How we know it's done] |
| [Action 2] | @[Name] | [Date] | [How we know it's done] |
| [Action 3] | @[Name] | [Date] | [How we know it's done] |

## Shout-Outs 🎉
- @[Name] for [what they did]
- @[Name] for [what they did]

## Notes
[Any additional notes or observations]

---
*Next Retrospective: [Date]*

---

Status Report Template

# [Project Name] Status Report - [Week of Date]

**Report Date:** [YYYY-MM-DD]
**Reporting Period:** [Start Date] - [End Date]
**Project Manager:** @[Name]
**Overall Status:** 🟢 On Track / 🟡 At Risk / 🔴 Off Track

## Executive Summary
[2-3 sentences: What's the current state? What are the key achievements? What needs attention?]

## Project Health

| Metric | Status | Details |
|--------|--------|---------|
| **Scope** | 🟢 / 🟡 / 🔴 | [Comment] |
| **Schedule** | 🟢 / 🟡 / 🔴 | [Comment] |
| **Budget** | 🟢 / 🟡 / 🔴 | [Comment] |
| **Quality** | 🟢 / 🟡 / 🔴 | [Comment] |
| **Team Morale** | 🟢 / 🟡 / 🔴 | [Comment] |

## Key Accomplishments
- ✅ [Accomplishment 1]
- ✅ [Accomplishment 2]
- ✅ [Accomplishment 3]

## Milestones Status

| Milestone | Target Date | Status | Actual/Forecast | Notes |
|-----------|-------------|--------|-----------------|-------|
| [Milestone 1] | [Date] | ✅ Complete | [Date] | [Notes] |
| [Milestone 2] | [Date] | 🔄 In Progress | On track | [Notes] |
| [Milestone 3] | [Date] | ⏳ Not Started | [Forecast] | [Notes] |

## Active Risks

### 🔴 Critical Risks
| Risk | Impact | Mitigation | Owner | Status |
|------|--------|------------|-------|--------|
| [Risk 1] | High | [Strategy] | @[Name] | [Update] |

### 🟡 Medium Risks
| Risk | Impact | Mitigation | Owner | Status |
|------|--------|------------|-------|--------|
| [Risk 2] | Medium | [Strategy] | @[Name] | [Update] |

## Issues & Blockers

### 🚨 Blockers
- [Blocker 1] - @[Owner] - **Escalated to:** [Person]
  - Impact: [What's blocked]
  - ETA to resolve: [Date]

### ⚠️ Issues
- [Issue 1] - @[Owner]
  - Status: [Update]

## Upcoming in Next Period
- [Activity 1]
- [Activity 2]
- [Activity 3]

## Budget Update (if applicable)
- **Total Budget:** [Amount]
- **Spent to Date:** [Amount] ([%])
- **Forecast to Complete:** [Amount]
- **Variance:** [Amount] ([%])

## Decisions Needed
| Decision | Why Needed | Deadline | Stakeholder |
|----------|-----------|----------|-------------|
| [Decision 1] | [Reason] | [Date] | @[Name] |

## Team Update
- **Current Team Size:** [N people]
- **Open Positions:** [N] ([Roles])
- **Recent Additions:** @[Name] - [Role]
- **Upcoming Departures:** [Names/Dates]

## Metrics (if applicable)
| Metric | This Period | Last Period | Trend | Target |
|--------|-------------|-------------|-------|--------|
| [Metric 1] | [Value] | [Value] | ↗️ / ↘️ / → | [Target] |
| [Metric 2] | [Value] | [Value] | ↗️ / ↘️ / → | [Target] |

## Links
- [Jira Project](link)
- [Roadmap](link)
- [Technical Docs](link)

---
*Next Status Report: [Date]*