Build Jira Document Format (Advanced)

Purpose

Master advanced Atlassian Document Format patterns for creating sophisticated, reusable Jira documents. Learn the builder pattern for fluent APIs, create specialized templates (EpicBuilder, IssueBuilder), design complex nested structures, and build document templates that scale from individual issues to epic planning.

When to Use This Skill

Explicit Triggers:

• “Create an ADF template for epics”
• “Build a document builder with fluent API”
• “Implement EpicBuilder for structured epics”
• “Design complex nested Jira document”
• “Create reusable Jira document templates”

Implicit Triggers:

• Repeatedly creating similar Jira documents manually
• Need consistent formatting across multiple issues/epics
• Building tools that generate Jira content programmatically
• Creating complex documents with code blocks, panels, and nested sections

Debugging Scenarios:

• “Why is my ADF document structure incorrect?”
• “How do I create nested panels with formatted content?”
• “Builder pattern not chaining correctly”

Quick Start

Create a formatted epic with problem statement, technical details, and acceptance criteria:

from jira_tool.formatter import EpicBuilder

# Create epic with builder
epic = EpicBuilder("Authentication Overhaul", "P0")
epic.add_problem_statement("Current auth is vulnerable to timing attacks")
epic.add_description("Implement OAuth2 with PKCE and secure session management")
epic.add_technical_details(
    requirements=[
        "PKCE flow support",
        "Session token encryption",
        "Rate limiting"
    ],
    code_example="""
    # OAuth2 flow
    token = oauth_client.get_token(code, pkce_verifier)
    session.set_secure_cookie(token)
    """
)
epic.add_acceptance_criteria([
    "All authentication tests pass",
    "Security audit complete",
    "Rate limiting works per RFC 6749"
])

# Get ADF for Jira API
adf = epic.build()

Or build step-by-step with the general-purpose builder:

from jira_tool.formatter import JiraDocumentBuilder

doc = JiraDocumentBuilder()
doc.add_heading("Epic: Authentication System", 1)
doc.add_heading("Problem", 2)
doc.add_panel("warning",
    {"type": "paragraph", "content": [
        doc.add_text("Current authentication has security vulnerabilities")
    ]}
)
doc.add_heading("Approach", 2)
doc.add_bullet_list([
    "Implement OAuth2 with PKCE",
    "Use session token encryption",
    "Add rate limiting"
])

adf = doc.build()

Instructions

Step 1: Understand the Builder Pattern

The builder pattern solves the problem of constructing complex objects through method chaining.

Without builder (verbose and error-prone):

doc = {
    "version": 1,
    "type": "doc",
    "content": [
        {
            "type": "heading",
            "attrs": {"level": 1},
            "content": [{"type": "text", "text": "Title"}]
        }
    ]
}

With builder (readable and safe):

doc = JiraDocumentBuilder()
doc.add_heading("Title", 1)
doc.add_paragraph(doc.add_text("Start: "), doc.bold("Bold"))
adf = doc.build()

Builder Benefits:

• Fluent API – Chain methods for readability
• Safety – Builders handle nesting automatically
• Reusability – Extend builders for custom layouts
• Validation – Catch errors early

Step 2: Master JiraDocumentBuilder

Method Chaining:

doc = JiraDocumentBuilder()
doc.add_heading("Title", 1) \
    .add_paragraph(doc.add_text("Introduction")) \
    .add_rule() \
    .add_heading("Section", 2) \
    .add_bullet_list(["Point 1", "Point 2"])

adf = doc.build()

Key Methods:

1. Structural Elements:

   doc.add_heading("Text", level=1)      # Level 1-6
   doc.add_paragraph(content_nodes)       # Mixed content
   doc.add_rule()                         # Horizontal line
   

2. Lists:

   doc.add_bullet_list(["Item 1", "Item 2"])
   doc.add_ordered_list(["First", "Second"], start=1)
   

3. Code Blocks:

   doc.add_code_block("def hello(): pass", language="python")
   

4. Panels (colored boxes):

   doc.add_panel("info", {"type": "paragraph", "content": [doc.add_text("Info")]})
   # Types: info, note, warning, success, error
   

5. Text Formatting:

   doc.bold("Bold text")
   doc.italic("Italic text")
   doc.code("inline_code")
   doc.strikethrough("Deleted")
   doc.link("Click here", "https://...")
   doc.add_text("Plain text")
   

Combining Formatting:

doc.add_paragraph(
    doc.bold("Important: "),
    doc.add_text("This is a "),
    doc.italic("complex"),
    doc.add_text(" message")
)

Step 3: Create Specialized Builders

For repeated structures, create helper functions or specialized builders:

Helper Function Pattern:

def add_titled_panel(builder, title, panel_type, content):
    """Add a heading followed by a panel."""
    builder.add_heading(title, 2)
    builder.add_panel(panel_type, {
        "type": "paragraph",
        "content": [builder.add_text(content)]
    })

# Usage
doc = JiraDocumentBuilder()
add_titled_panel(doc, "⚠️ Risks", "warning", "Performance impact on v1 API")

EpicBuilder Pattern:

class EpicBuilder:
    """Pre-formatted epic template."""

    def __init__(self, title: str, priority: str = "P1"):
        self.builder = JiraDocumentBuilder()
        self.builder.add_heading(f"🎯 {title}", 1)
        self.builder.add_paragraph(
            self.builder.bold("Priority: "),
            self.builder.add_text(priority)
        )

    def add_problem_statement(self, statement: str):
        self.builder.add_heading("Problem Statement", 2)
        self.builder.add_panel("warning", {
            "type": "paragraph",
            "content": [self.builder.add_text(statement)]
        })
        return self

    def add_acceptance_criteria(self, criteria: list[str]):
        self.builder.add_heading("Acceptance Criteria", 2)
        self.builder.add_ordered_list(criteria)
        return self

    def build(self):
        return self.builder.build()

See references/advanced-patterns.md for full EpicBuilder and BugReportBuilder implementations with inheritance patterns, composition, and testing strategies.

Step 4: Implement Builder Best Practices

Return self for Chaining:

class CustomBuilder:
    def add_something(self) -> "CustomBuilder":
        # ... implementation
        return self  # Allow chaining

Validate Before Building:

def build(self) -> dict:
    """Build and validate before returning."""
    if not self.title:
        raise ValueError("Title is required")
    if not self.builder.content:
        raise ValueError("Content is empty")
    return self.builder.build()

Document Structure:

class DocumentTemplate:
    """
    Template for standard epic documentation.

    Structure:
    - Header (title, priority, timeline)
    - Problem statement (warning panel)
    - Solution approach (bullet list)
    - Technical requirements (ordered list)
    - Acceptance criteria (ordered list)
    """
    def __init__(self, title: str):
        pass

Supporting Files

References

• references/advanced-patterns.md – Builder inheritance, composition patterns, template methods, complex nested structures, performance considerations, testing strategies, full implementation examples for EpicBuilder and BugReportBuilder

Examples

• examples/epic-examples.md – Database migration epic, two-factor authentication feature, bug report builder, authentication system epic, method chaining examples, complex nested structures with 6 complete working examples

Expected Outcomes

Successful Document Building:

• ADF validates correctly with Jira API
• Documents render properly in Jira UI
• Builders return valid JSON structure
• Method chaining works smoothly

Builder Template Creation:

• Consistent structure across similar documents
• Reusable code reduces duplication
• Custom builders extend base functionality
• Validation catches errors early

Requirements

Core Requirements

• Python 3.10+ (for type hints and dataclass improvements)
• jira_tool.formatter module containing:
  • JiraDocumentBuilder – General-purpose builder
  • EpicBuilder – Epic-specific template
  • IssueBuilder – Issue-specific template

For Testing Builders

• Jira REST API v3 access (to submit built documents)
• Environment variables: JIRA_BASE_URL, JIRA_USERNAME, JIRA_API_TOKEN
• Test project where you can create issues

Recommended Tools

• jira_adf_validator: npm install -g jira-adf-validator
• Python json: Built-in (for validating ADF structure)
• curl: For testing API submissions

Red Flags to Avoid

• Manual ADF Construction – Use builders instead of raw dicts
• No Validation – Always validate before submitting to Jira
• Builder Reuse – Create new builder instance for each document
• Missing Return self – Breaks method chaining
• Hardcoded Structure – Use builders for flexibility
• No Type Hints – Type hints improve IDE support and catch errors
• Verbose Paragraph Construction – Use text helper methods
• No Error Handling – Catch validation errors in build()
• Inconsistent Templates – Use specialized builders for consistency

See Also

• work-with-adf – Basic ADF concepts and structure
• jira-api – API endpoints for creating/updating documents
• export-and-analyze-jira-data – Generating report documents
• src/jira_tool/formatter.py – Full builder implementation reference

Notes

• EpicBuilder and IssueBuilder are provided by jira_tool.formatter module
• ADF structure must have version:1, type:”doc”, and content array
• Panels must contain content nodes (paragraphs, headings, etc.)
• Code blocks support language parameter for syntax highlighting
• Method chaining requires returning self from all builder methods
• Test builders with jira-adf-validator before submitting to Jira
• See references/advanced-patterns.md for builder inheritance, composition patterns, and full EpicBuilder/BugReportBuilder implementations
• See examples/epic-examples.md for 6 complete working examples including database migration, two-factor authentication, and complex nested structures