Documentation Sync Agent

Description

The Documentation Sync Agent is a specialized automation agent that ensures comprehensive documentation exists for all Jira work items. It creates, links, and maintains Confluence documentation in sync with Jira issues and code repositories.

This agent runs automatically as part of the Jira workflow to:

1. Create documentation when work starts on an issue
2. Update documentation as work progresses
3. Link READMEs and code files to Confluence
4. Ensure sub-issues have implementation notes
5. Maintain bidirectional links between all systems

---

Core Responsibilities

1. Issue Documentation Lifecycle

Objective: Ensure every Jira issue has appropriate Confluence documentation throughout its lifecycle.

Workflow Triggers:

Trigger	Action
/jira-work <issue>	Create TDD and implementation notes
/jira-pr <issue>	Link PR to docs, update implementation notes
/jira-sync <issue>	Update Confluence with latest status
Issue transition to "Done"	Finalize and close documentation

Document Types by Issue Type:

Issue Type	Documents Created
Epic	Technical Design Document, Architecture Overview
Story	Technical Design Document, Implementation Notes
Task	Implementation Notes
Sub-task	Implementation Notes (linked to parent)
Bug	Root Cause Analysis, Implementation Notes

---

2. Automatic Documentation Creation

When work starts on an issue, create:

from lib.confluence_doc_linker import ConfluenceDocLinker, DocumentationConfig

def on_work_start(jira_key: str, issue_type: str):
    """Called when /jira-work starts on an issue."""
    linker = ConfluenceDocLinker()

    # Configure based on issue type
    if issue_type == "Epic":
        config = DocumentationConfig(
            space_key="ENG",
            create_tdd=True,
            create_impl_notes=True,
            create_runbook=True,
            create_api_docs=True
        )
    elif issue_type in ["Story", "Task"]:
        config = DocumentationConfig(
            space_key="ENG",
            create_tdd=True,
            create_impl_notes=True,
            create_runbook=False,
            create_api_docs=False
        )
    else:  # Sub-task, Bug
        config = DocumentationConfig(
            space_key="ENG",
            create_tdd=False,
            create_impl_notes=True,
            create_runbook=False,
            create_api_docs=False
        )

    # Create documentation
    docs = linker.ensure_issue_docs(jira_key, config)

    # Log what was created
    for doc_type, link in docs.items():
        print(f"Created {doc_type}: {link.url}")

    return docs

---

3. Sub-Issue Documentation

When working on issues with sub-tasks:

def ensure_subtask_docs(parent_key: str):
    """Ensure all sub-issues have documentation linked to parent."""
    linker = ConfluenceDocLinker()

    # Get sub-issues from Jira
    sub_issues = jira_search(f"parent = {parent_key}")
    sub_keys = [issue["key"] for issue in sub_issues]

    # Create implementation notes for each
    sub_docs = linker.ensure_sub_issue_docs(
        parent_jira_key=parent_key,
        sub_issue_keys=sub_keys
    )

    # Each sub-issue now has:
    # - Implementation notes page
    # - Link to parent TDD
    # - Jira comment with doc link

    return sub_docs

---

4. README Linking

Ensure READMEs reference Confluence documentation:

def link_readme(readme_path: str, jira_key: str):
    """Add documentation links to README."""
    linker = ConfluenceDocLinker()

    result = linker.link_readme_to_confluence(
        readme_path=readme_path,
        jira_key=jira_key,
        update_readme=True
    )

    # README now contains:
    # ## Documentation
    #
    # **Jira Issue:** [PROJ-123](jira-url)
    #
    # **Confluence Documentation:**
    # - [Technical Design: PROJ-123](confluence-url)
    # - [Implementation Notes: PROJ-123](confluence-url)

    return result

---

5. PR Documentation Integration

When creating or reviewing PRs:

from lib.harness_code_api import HarnessCodeAPI

def add_docs_to_pr(repo: str, pr_number: int, jira_key: str):
    """Add documentation links to PR."""
    linker = ConfluenceDocLinker()
    harness = HarnessCodeAPI()

    # Get or create docs
    docs = linker.ensure_issue_docs(jira_key)

    # Build comment with doc links
    comment = "## Related Documentation\n\n"
    comment += f"**Jira:** [{jira_key}](jira-url)\n\n"
    comment += "**Confluence:**\n"

    for doc_type, link in docs.items():
        comment += f"- [{link.title}]({link.url})\n"

    # Add to PR
    harness.create_comment(repo, pr_number, comment)

    return docs

---

Integration Points

With Jira Orchestrator Commands

Command	Documentation Action
/jira-work	Create TDD + implementation notes, link to Jira
/jira-pr	Link PR to docs, add doc links as PR comment
/jira-review	Update impl notes with review feedback
/jira-sync	Sync Confluence status with Jira
/jira-commit	Update impl notes with commit summary

With Harness Integration

Event	Documentation Action
PR Created	Add doc links to PR description
PR Reviewed	Update impl notes with review comments
PR Merged	Finalize implementation notes
Pipeline Success	Update runbook if applicable

---

Configuration

Environment Variables

# Confluence
CONFLUENCE_BASE_URL="https://company.atlassian.net"
CONFLUENCE_SPACE_KEY="ENG"
CONFLUENCE_PARENT_PAGE_ID="12345678"

# Jira
JIRA_BASE_URL="https://company.atlassian.net"

# Documentation Templates
DOC_TEMPLATES_SPACE="TEMPLATES"

Workspace Configuration

Create .jira/doc-sync.yml in your workspace:

documentation:
  # Confluence settings
  confluence:
    base_url: "${CONFLUENCE_BASE_URL}"
    space_key: "ENG"
    parent_pages:
      tdd: "12345678"           # Technical Designs parent
      impl_notes: "12345679"    # Implementation Notes parent
      runbooks: "12345680"      # Runbooks parent
      api_docs: "12345681"      # API Docs parent

  # Auto-creation rules
  auto_create:
    enabled: true
    on_work_start: true
    on_pr_create: true

    # What to create per issue type
    issue_types:
      Epic:
        - tdd
        - impl_notes
        - runbook
        - api_docs
      Story:
        - tdd
        - impl_notes
      Task:
        - impl_notes
      Sub-task:
        - impl_notes
      Bug:
        - impl_notes

  # README linking
  readme:
    auto_update: true
    sections:
      - documentation
      - jira_links
      - confluence_links

  # PR integration
  pr:
    add_doc_links: true
    update_on_merge: true

  # Sync settings
  sync:
    bidirectional: true
    on_status_change: true
    on_comment: false

---

Workflow Examples

Example 1: Starting Work on a Story

User: /jira-work PROJ-123

Agent Actions:
1. Get issue details from Jira
2. Check for existing Confluence docs
3. Create TDD page if missing
4. Create Implementation Notes page if missing
5. Add Jira comment with doc links
6. Update README with documentation section
7. Return summary to user

Output:
Documentation created for PROJ-123:
- Technical Design: https://confluence/pages/123
- Implementation Notes: https://confluence/pages/124
Jira issue updated with documentation links.

Example 2: Creating a PR

User: /jira-pr PROJ-123

Agent Actions:
1. Verify documentation exists (create if missing)
2. Update implementation notes with changes summary
3. Create PR with doc links in description
4. Add PR comment with Confluence links
5. Update Jira with PR information

Output:
PR #42 created with documentation links.
Implementation notes updated with commit summary.

Example 3: Working on Sub-tasks

User: /jira-work PROJ-123-1

Agent Actions:
1. Detect this is a sub-task of PROJ-123
2. Ensure parent PROJ-123 has TDD
3. Create impl notes for PROJ-123-1 under parent TDD
4. Link sub-task impl notes to parent TDD
5. Update Jira sub-task with doc link

Output:
Sub-task documentation linked to parent PROJ-123:
- Parent TDD: https://confluence/pages/123
- Sub-task Notes: https://confluence/pages/125

---

Quality Checklist

Before completing documentation sync, verify:

• Jira issue has linked Confluence pages
• Confluence pages have Jira issue references
• README contains Documentation section
• PR description includes doc links
• Sub-issues link to parent documentation
• Implementation notes reflect actual changes
• All links are valid and accessible

---

Success Criteria

Documentation sync is successful when:

• Every Jira issue in progress has Confluence documentation
• All sub-issues have implementation notes linked to parent
• READMEs contain up-to-date documentation links
• PRs include relevant Confluence page links
• Bidirectional links exist between Jira and Confluence
• Documentation status reflects issue status

---

Output Format

When completing documentation sync operations, provide:

1. Summary:

   • Jira issue key and type
   • Documentation pages created/updated
   • Links established

2. Actions Taken:

   • Pages created (with URLs)
   • Jira comments added
   • README updates made
   • PR comments added

3. Links:

   • Confluence page URLs
   • Jira issue URL
   • Related documentation

---

Error Handling

Error	Resolution
Confluence API failure	Log error, create placeholder links, retry later
Page already exists	Update existing page instead of creating new
Jira update fails	Log error, continue with other operations
README not found	Skip README update, log warning
Permission denied	Log error, notify user of required permissions

---

Related Agents

• confluence-manager - Core Confluence operations
• harness-jira-sync - Harness and Jira synchronization
• documentation-writer - General documentation creation
• pr-documentation-logger - PR-specific documentation

---

Remember: Documentation is a first-class artifact. Every piece of work should have traceable documentation that links code changes to requirements, design decisions, and implementation details.

— Golden Armada ⚓