Jira Flow Lens

A Python tool for analyzing Jira workflow metrics and identifying bottlenecks using AI-powered insights. Jira Flow Lens processes exported Jira data to compute flow metrics (cycle time, WIP, status distribution) and generates actionable improvement recommendations.

Overview

Jira Flow Lens helps project managers, scrum masters, and development team leads understand their team's workflow efficiency by:

• Computing key flow metrics from Jira exports (median/p90 cycle time, status distribution, assignee workload)
• Analyzing bottlenecks and work-in-progress (WIP) patterns
• Generating AI-powered, actionable improvement recommendations

Current Limitations

This tool currently only works with Ollama as the LLM provider. You must have Ollama installed and running locally on your machine. Support for additional LLM providers (OpenAI, Anthropic, etc.) is planned for future releases.

Prerequisites

1. Python 3.13 or higher
2. Ollama - Install from ollama.ai
3. Ollama Model - Pull one of the supported models:

   # Option 1: GPT-OSS 20B (default in code)
   ollama pull gpt-oss:20b
   
   # Option 2: Llama 3.2 (alternative)
   ollama pull llama3.2

4. uv (Python package manager) - Install from astral.sh/uv

Installation

1. Clone the repository:

   git clone <repository-url>
   cd jira-flow-lens

2. Install dependencies using uv:

   uv sync

Exporting Data from Jira

To use this tool, you need to export your Jira issues as a CSV file:

1. In Jira, navigate to Issues → Search for Issues
2. Apply filters to select the issues you want to analyze (e.g., specific project, time range)
3. Click Export → Export CSV (All fields)
4. Save the exported file as jira-export.csv in the csv/ directory of this project

Important columns: The tool works best when your export includes these columns:

• Created - Issue creation date
• Resolved or Resolution Date - Issue resolution date
• Status - Current status
• Assignee - Person assigned to the issue
• Updated - Last update date (optional)

Usage

1. Ensure Ollama is running:

   ollama serve

2. Place your Jira CSV export in the csv/ directory as jira-export.csv

3. Run the analysis:

   uv run python main.py

The tool will:

• Load and preview your CSV data
• Parse date columns automatically
• Compute flow metrics (cycle time, status distribution, assignee workload)
• Generate AI-powered improvement recommendations

Output

The tool provides:

1. CSV Preview - Sample of loaded data and column information
2. Deterministic Metrics:
   • Median and P90 cycle time (in days)
   • Issue distribution by status
   • Top 10 assignees with open issues
3. AI-Generated Summary - Bullet-point analysis with 3-5 specific improvement actions focused on WIP limits, bottlenecks, and cycle time optimization

Configuration

All configuration settings are centralized in config.py to make customization easy without editing the main script.

Common Configuration Changes

Change the Ollama model (edit config.py:24-29):

OLLAMA_CONFIG = {
    "model": "llama3.2",  # Change from "gpt-oss:20b" to "llama3.2"
    "validate_model_on_init": True,
    "temperature": 0.1,
    "num_predict": 1536,
    "num_ctx": 4096,
}

Adjust temperature for creativity vs. determinism (in OLLAMA_CONFIG):

• Lower values (0.0-0.3): More deterministic, follows format strictly
• Higher values (0.7-1.0): More creative, may diverge from format

Customize Jira column names (edit config.py:7-16) if your export uses different names:

JIRA_COLUMNS = {
    "created": "Created Date",  # Or whatever your export calls it
    "status": "Issue Status",
    "assignee": "Assigned To",
    # ... etc
}

Adjust status classification (edit config.py:18-26) to match your Jira workflow:

DONE_STATUS_VALUES = {
    "done",
    "resolved",
    "closed",
    # Add your custom completed statuses here
}

Change number of top assignees (edit config.py:45-48):

METRICS_CONFIG = {
    "top_assignees_count": 15,  # Changed from 10 to 15
}

All Configuration Options

See config.py for the complete list of settings:

• CSV_FILE_PATH - Location of your Jira export
• JIRA_COLUMNS - Column name mappings for different Jira exports
• DONE_STATUS_VALUES - Status values considered "completed"
• OLLAMA_CONFIG - Ollama model and inference parameters
• LLM_PROMPT - The prompt template for AI analysis
• METRICS_CONFIG - Metrics computation settings

Project Structure

jira-flow-lens/
├── csv/
│   └── jira-export.csv     # Place your Jira export here
├── config.py               # Configuration settings
├── main.py                 # Main analysis script
├── pyproject.toml          # Project dependencies
└── README.md               # This file

Roadmap

• Support for additional LLM providers (OpenAI, Anthropic, Google)
• Interactive web dashboard
• Historical trend analysis
• Configurable metric definitions
• Custom report templates

Troubleshooting

CSV file not found: Ensure your export is saved as csv/jira-export.csv

Ollama connection error: Make sure Ollama is running (ollama serve)

Model not found: Pull the required model using ollama pull <model-name>

Date parsing issues: The tool attempts to parse common Jira date column names. If your export uses different names, dates might not be parsed correctly. Customize JIRA_COLUMNS in config.py to match your export.

License

[Add your license here]

Contributing

[Add contribution guidelines here]