📝 Jira Publisher

A focused Python tool for publishing Jira analysis results to Confluence with AI-powered insights.

✨ Key Features

• 📝 Confluence Publishing: Publish sprint analysis and backlog hygiene reports to Confluence
• 🤖 AI-Powered Insights: Generate intelligent summaries and recommendations using Google Gemini AI
• 🎯 Sprint Analysis Publishing: Create rich HTML reports for sprint completion analysis
• 🧹 Backlog Hygiene Publishing: Publish comprehensive backlog health assessments
• 🔗 Rich HTML Reports: Generate reports with clickable Jira ticket links
• ⚙️ Flexible Configuration: Support for multiple projects and spaces

Features

• Sprint Analysis: Analyze completion rates by month, recent sprints, or specific sprint names
• Sprint-by-Name Analysis: Analyze any sprint by its exact name with case-insensitive matching
• Average Completion Rate: Quick overview of team performance across last 4 sprints
• Active Sprint Monitoring: Track current progress of active sprints
• Backlog Hygiene Analysis: Comprehensive backlog health assessment with hygiene scoring
• AI-Powered Summaries: Generate intelligent sprint achievement summaries using Google Gemini
• Confluence Publishing: Automatically publish rich HTML reports with clickable ticket links
• Team Performance Context: Compare individual sprint performance against team averages
• Export Support: Export results to CSV and JSON formats
• Multiple CLI Interfaces: Choose from focused or comprehensive command-line tools

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd my_jira_analyzer

# Install dependencies
pip install -r requirements.txt

# Create configuration
python cli.py config --create-sample

Basic Usage

# Publish sprint analysis to Confluence
python main.py publish_sprint_review --sprint-name "Sprint 42"

# Publish backlog hygiene analysis
python main.py publish_backlog_hygiene

# Test Confluence connection
python main.py test

Package Structure

src/
├── gen_ai/                # AI-powered analysis modules
│   ├── sprint_summarizer.py          # Sprint achievement summaries
│   ├── hygiene_analyzer.py           # Backlog hygiene recommendations
│   └── prompts/                      # AI prompt templates
│       ├── sprint_summarizer_prompts.py
│       └── backlog_hygiene_prompts.py
├── analyzers/             # Analysis modules
│   ├── sprint_analyzer.py # Sprint analysis logic
│   └── backlog_hygiene_analyzer.py # Backlog hygiene analysis
├── publishers/            # Publishing modules
│   └── confluence_publisher.py # Confluence integration
├── clients/               # External service clients
│   └── jira_client.py     # Jira API client
├── configs/               # Configuration management
│   └── config.py          # Configuration handling
├── cli/                   # Command-line interface
│   └── publish_cli.py     # Publishing CLI
└── utils/                 # Utility functions
    └── utils.py           # Shared utilities

Configuration

Setup Your API Keys

1. Copy the example configuration:

   cp src/configs/config.json.example config.json

2. Edit config.json with your actual credentials:

   {
     "jira": {
       "url": "https://your-company.atlassian.net",
       "username": "your-email@company.com",
       "api_token": "your-actual-jira-api-token",
       "project_key": "YOUR_PROJECT_KEY"
     },
     "confluence": {
       "url": "https://your-company.atlassian.net/wiki",
       "username": "your-email@company.com",
       "api_token": "your-actual-confluence-api-token",
       "space": "YOUR_SPACE_KEY",
               "sprint_completion_parent_page": "Sprint Reviews",
       "backlog_hygiene_parent_page": "Backlog Reports"
     },
     "ai": {
       "gemini_api_key": "your-actual-gemini-api-key"
     }
   }

3. Your config.json is automatically ignored by git - it won't be committed to the repository.

Configuration Options

Confluence Publishing:

• space: Confluence space for all publishing
• sprint_completion_parent_page: Parent page for sprint completion analysis reports
• backlog_hygiene_parent_page: Parent page for backlog hygiene reports

If parent pages are not specified, reports will be created at the root level of the space.

Getting API Tokens

• Jira/Confluence: Create API Token
• Google AI: Get Gemini API Key

Available Commands

All commands are publishing-focused and generate Confluence reports with rich HTML formatting and AI insights:

Sprint Analysis Publishing

# Publish sprint analysis to Confluence
python main.py publish_sprint_review --sprint-name "Sprint 42"

# Custom configuration
python main.py publish_sprint_review --sprint-name "Sprint 42" \
  --title "Custom Report Title" \
  --parent "Sprint Reviews"

Backlog Hygiene Publishing

# Publish backlog hygiene analysis (automatically includes current week)
python main.py publish_backlog_hygiene
# Creates: "Analysis - W26 2024" (under default parent page)

# With custom title
python main.py publish_backlog_hygiene --title "Weekly Backlog Health Check"

Utility Commands

# Test Confluence connection
python main.py test

Command Options

Global Options:

• --config, -c: Path to configuration file (default: src/configs/config.json)

For publish_sprint_review:

• --sprint-name, -n: Sprint name to analyze and publish (required)
• --title, -t: Page title (auto-generated if not provided)
• --parent, -p: Parent page title
• --update: Update existing page if found

For publish_backlog_hygiene:

• --title, -t: Page title (default: "Analysis - W{week} {year}")

Note: The Confluence space is automatically read from space in your config.json file.

Example Usage

# Publish sprint review by name
python main.py publish_sprint_review --sprint-name "Sprint 42"

# Publish with custom title and parent page
python main.py publish_sprint_review --sprint-name "Slow Sloths (W25-W26)" --title "Custom Report Title" --parent "Sprint Reports"

# Publish backlog hygiene analysis
python main.py publish_backlog_hygiene

# Publish backlog hygiene with custom title
python main.py publish_backlog_hygiene --title "Weekly Backlog Health Check"

# Test Confluence connection
python main.py test

Help

To see all available commands and options:

python main.py --help

To see help for a specific command:

python main.py publish_sprint_review --help
python main.py publish_backlog_hygiene --help
python main.py test --help

Features in Detail

🎯 Sprint-by-Name Analysis

• Case-insensitive sprint name matching
• Searches across active, closed, and future sprints
• Detailed task breakdown and completion metrics
• Sprint state and date information

📊 Team Performance Context

• Average completion rate of last 4 closed sprints
• Individual sprint performance comparison
• Best and worst performing sprint identification
• Trend analysis and insights

🧹 Backlog Hygiene Analysis

• Hygiene Score (0-100%): Overall backlog health assessment
• Completeness Analysis: Track issues with descriptions, epics, priorities, and story points
• Age Distribution: Identify how long issues have been in backlog (0-7, 8-30, 31-90, 91-180, 180+ days)
• Stale Issue Detection: Find issues older than configurable threshold (default: 90 days)
• Incomplete Issue Analysis: Identify issues missing critical information
• Priority Distribution: Analyze priority assignment across backlog
• Epic Assignment: Track orphaned issues without epic assignments
• AI-Powered Recommendations: Get Scrum expert insights and actionable suggestions
• 📚 Detailed Hygiene Algorithm Guide

🤖 AI-Powered Insights

• Sprint Summarizer: Intelligent sprint achievement summaries with epic context
• Hygiene Analyzer: Scrum expert recommendations for backlog improvement
• Strategic Context: Epic descriptions and business value focus
• Plain Text Output: Confluence-ready formatting without markdown
• Fallback Summaries: Structured recommendations when AI unavailable
• 📚 Detailed AI Prompt Engineering Guide

🔗 Rich Confluence Reports

• Clickable Jira ticket links
• Professional HTML formatting
• Team performance context sections
• Visual indicators and progress bars
• Responsive design for all devices

📈 Export and Integration

• CSV export for spreadsheet analysis
• JSON export for programmatic use
• Multiple output formats supported
• Easy integration with other tools

Development

Package Structure

The codebase follows a clean, modular architecture:

• src/gen_ai/: AI-powered analysis with dedicated summarizers and prompt templates
• src/analyzers/: Core analysis logic and algorithms
• src/publishers/: Output and publishing modules
• src/cli/: Command-line interfaces and user interaction
• src/clients/: External service integrations
• src/configs/: Configuration management

Key Classes

• SprintAnalyzer: Core analysis engine with sprint-by-name and average completion rate features
• BacklogHygieneAnalyzer: Comprehensive backlog health assessment with hygiene scoring
• SprintSummarizer: AI-powered sprint achievement summaries with epic context
• HygieneAnalyzer: AI-powered backlog recommendations and Scrum expert insights
• JiraClient: Jira API wrapper with enhanced sprint search and epic detection capabilities
• ConfluencePublisher: Rich HTML report generation with AI integration

Installation for Development

# Install in development mode
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Requirements

• Python 3.7+
• Jira API access
• Confluence API access (for publishing)
• Google AI API key (optional, for AI features)

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

1. Check the configuration setup
2. Test API connections using python main.py test
3. Review error messages for specific guidance
4. Open an issue with detailed information