jira-spillover-chart

A reporting extension for jira-spillover-get that transforms spillover data into comprehensive Excel workbooks with charts, pivot tables, and performance insights enabling teams to analyse delivery patterns and optimise workflow efficiency.

Table of contents

• Why spillover matters
• What this tool does
• Key features
  • Who should use this tool
  • Use cases
  • Project structure
• Prerequisites
• Set up
• Build the application
  • Windows
  • Linux/macOS
  • Building from source
  • Testing
• Usage
  • Basic execution
  • Command line options
  • Command line parameters
  • Parameters
  • Examples
  • Automated execution
• Spillover Report Output
• Interpreting results
  • Key metrics to review
  • Common patterns and what they mean
  • Recommended actions
• How jira-spillover-chart works
  • Data Processing
  • Excel Generation
• Error handling
• Logging
• Performance considerations
• Troubleshooting
  • Common issues
  • Debug information
• Contributing
• License
• Support

Why spillover matters

Spillover represents an inability to complete what was planned within a sprint. While occasional spillover can be justified, ongoing spillover can significantly impact Agile delivery. It indicates issues with planning and execution, leading to delays and reduced efficiency.

The biggest challenge with spillover is tracking its occurrence, as Jira doesn't provide built-in tools specifically for this purpose. This tool fills that gap by generating rich visual reports and analytics from raw spillover data.

For more detailed information on the impact of spillover and recommended approaches, see my blog article "Mastering agile spillover, analysis and strategic solutions".

What this tool does

This tool takes the tab-separated output file created by jira-spillover-get and generates fifteen comprehensive Excel-based reports including:

1. Pre-built pivot tables and charts an extensive range of data visualisations
2. Raw data sheet containing all spillover work items

The results are presented in a rich Excel workbook that can be shared with stakeholders and used for analysis.

Can be run from the command line or interactively, making it suitable for both automated pipelines and ad-hoc analysis.

Key features

• Command line interface full command line support with interactive fallback
• TSV file processing reads and validates tab-separated spillover data
• Excel XLSX output creates formatted Excel files with proper column styling
• Data validation comprehensive input validation and error handling
• Progress tracking real-time progress indicators for large datasets
• Comprehensive logging optional detailed logging to timestamped files
• Cross platform Windows, Linux, and macOS executables provided
• Date formatting proper Excel date formatting for date columns
• Interactive mode prompts for missing parameters when run without arguments

Who should use this tool

• Agile teams looking to analyse and visualise their spillover data
• Scrum Masters, and Agile/Product Coaches needing formatted reports
• Development Team Leads sharing spillover analysis with stakeholders
• Project Managers requiring Excel-based delivery metrics

Use cases

• Converting weekly/monthly/quarterly spillover TSV reports to Excel format
• Creating formatted Excel files for stakeholder reporting
• Automated processing of spillover reports in CI/CD pipelines
• Batch conversion of multiple TSV files to Excel format

Project structure

jira-spillover-chart/
├── .gitignore
├── LICENSE              # User license
├── README.md            # The file you're reading now :D
├── spillover-count-by-component.jpg  # sample XLSX image
├── spillover-count-by-epic.jpg       # sample XLSX image
├── spillover-count-by-PI.jpg         # sample XLSX image
├── spillover-raw-data.jpg            # sample XLSX image
├── spillover-data-filters.jpg        # sample analysis filters
├── build/
│   ├── jira-spillover-chart.exe      # Windows executable
│   ├── jira-spillover-chart-linux    # Linux executable
│   └── jira-spillover-chart-macos    # macOS executable
├── go/
│   ├── build.bat        # Windows build script
│   ├── build.sh         # Unix/Linux build script
│   ├── go.mod           # Go module definition
│   ├── go.sum           # Go module dependencies
│   ├── jira-spillover-chart.go # Go application source code
│   ├── resource.syso    # Dynamically created by go generate
│   ├── template.xlsx    # Excel template used for report generation
│   └── versioninfo.json # Windows resource definition (file version details)
└── samples/
    ├── clear-pivot-cache.vba         # VBA module for Excel to clear the pivot cache
    ├── go.mod                        # Go module definition
    ├── jira-spillover-synth-data.exe # application to create sample data
    ├── jira-spillover-synth-data.go  # Go application source code
    ├── pivotCacheDefinition1.xml     # example showing forced update of pivot cache on open
    ├── synthetic_data.tsv            # 5,000 rows of sample data
    └───.copilot
        ├── context.json              # Defines context for Copilot (e.g. project goals, domain-specific hints)
        └── copilot-instructions.md   # Provides natural language guidance to steer Copilot’s completions

Prerequisites

1. Input Data TSV file generated by jira-spillover-get
2. Operating System Windows, Linux, or macOS
3. File Permissions read access to input files, write access to output directory

Set up

1. Generate spillover data using the jira-spillover-get tool
2. Run the jira-spillover-chart tool

Build the application

Pre-built binaries are in the .\build folder.

Windows

cd go
build.bat

Linux/macOS

cd go
chmod +x build.sh
./build.sh

Building from source

# Build for current platform
go build -o jira-spillover-chart jira-spillover-chart.go

# Build for Windows
GOOS=windows GOARCH=amd64 go build -o jira-spillover-chart.exe jira-spillover-chart.go

# Build for Linux  
GOOS=linux GOARCH=amd64 go build -o jira-spillover-chart-linux jira-spillover-chart.go

# Build for macOS
GOOS=darwin GOARCH=amd64 go build -o jira-spillover-chart-mac jira-spillover-chart.go

Testing

# Run with help to verify build
./jira-spillover-chart -help

# Test with sample data
./jira-spillover-chart -inputfile ../samples/synthetic_data.tsv -outputfile spillover_chart.xlsx -debug -log

Usage

Basic execution

Execute the application from the command line. It will prompt you for required parameters if not provided:

jira-spillover-chart.exe

Command line options

View available command-line parameters:

jira-spillover-chart.exe -?

Command line parameters

jira-spillover-chart.exe [-inputfile input.tsv] [-outputfile output.xlsx] 
    [-templatefile template.xlsx] [-log] [-debug] [-?]

Parameters

• -inputfile path to input TSV file (default: spillover_report.tsv)
• -outputfile path to output Excel file (default: spillover_chart.xlsx)
• -templatefile path to Excel template file (default: template.xlsx)
• -log enable logging to file
• -debug enable debug messages (display detailed processing information)
• -? show help message

Examples

Command line with all parameters:

jira-spillover-chart.exe -inputfile spillover_data.tsv -outputfile analysis.xlsx -templatefile template.xlsx -log -debug

Interactive mode (no parameters):

jira-spillover-chart.exe

Basic conversion:

jira-spillover-chart.exe -inputfile weekly_report.tsv -outputfile weekly_analysis.xlsx -templatefile template.xlsx

Automated execution

The command line parameters allow you to run this application from a scheduler like Windows Task Scheduler or via a batch file:

jira-spillover-chart.exe -inputfile spillover_data.tsv -outputfile monthly_report.xlsx -templatefile template.xlsx -log

Spillover Report Output

The application processes the nominated TSV input file created by jira-spillover-get and through a template Excel file:

• Validates all input data for completeness and format
• Converts text dates to properly formatted Excel dates
• Applies consistent column widths and text alignment
• Preserves all original spillover data columns
• Maintains tab-separated structure in Excel format
• on first opening the output XLSX file, all pivot tables and charts are refreshed

The resultant Excel XLSX file contains sixteen worksheets:

1. ByEpicCount - epics that had work items that spilled over into subsequent sprints, and the count of work items that spilled over.
2. ByEpicSP - epics that had work items that spilled over into subsequent sprints, and the sum of story points that spilled over.
3. ByEpicSprints - epics that had work items that spilled over into subsequent sprints, and the count of sprints that these work items spilled over.
4. ByWkItemSP - work items that spilled over into subsequent sprints, and the count of story points that spilled over.
5. ByWkItemSprints - work items that spilled over into subsequent sprints, and the count of sprints that spilled over.
6. ByAssigneeCount - assignees that had work items that spilled over into subsequent sprints, and the count of these work items that spilled over.
7. ByAssigneeSP - assignees that had work items that spilled over into subsequent sprints, and the sum of story points that spilled over.
8. ByAssigneeSprints - assignees that had work items that spilled over into subsequent sprints, and the sum of sprints.
9. ByPI-Count - work items that spilled over into subsequent sprints, and the count of sprints over a PI for these work items.
10. ByPI-SP - work items that spilled over into subsequent sprints, and the sum of story points that spilled over.
11. ByPIProject - work items that spilled over into subsequent sprints, by project (only useful when data exists for multiple projects).
12. ByTypeCount - work items that spilled over into subsequent sprints, and their issue type.
13. ByCompCount - components that spilled over into subsequent sprints, and the count of components that spilled over.
14. ByCompSP - components that spilled over into subsequent sprints, and the story points that spilled over.
15. ByCompSprints - components that spilled over into subsequent sprints, and the sum of the number of sprints that spilled over.
16. Spillover Data - the raw data

Spillover count by Program Increment

Spillover count by Component

Spillover count by epic

Spillover raw data

Spillover data filters

Interpreting results

Key metrics to review

1. Spillover Rate Trend overall direction of spillover over time
2. Peak Spillover Periods identification of problematic time frames
3. Team Performance individual and team spillover patterns
4. Epic Analysis epics with highest spillover impact
5. Issue Type Patterns which types of work spill over most frequently

Common patterns and what they mean

• Increasing Trend may indicate growing technical debt or scope creep
• Seasonal Patterns could reflect holiday periods or release cycles
• Team Hotspots specific individuals or teams with high spillover
• Epic Correlations certain epics consistently causing spillover

Recommended actions

• Use trend analysis to set realistic spillover reduction targets
• Focus improvement efforts on highest-impact areas identified in charts
• Share dashboard with stakeholders for data-driven discussions
• Track improvement initiatives using before/after comparisons

How jira-spillover-chart works

Data Processing

The Go application processes TSV data through:

1. Command line argument parsing and validation
2. TSV file reading and parsing with header validation
3. Data type conversion and date formatting
4. Worksheet population with formatted data

Excel Generation

The application creates Excel files by:

• Reading TSV files with proper tab-separated parsing
• Converting date strings to Excel date values with dd/mm/yyyy formatting
• Creating formatted tables with proper column widths
• Saving as standard XLSX format compatible with all Excel versions

Error handling

The application includes comprehensive error handling for:

• Missing or corrupted input TSV files
• Invalid TSV format or missing headers
• File permission issues (read/write access)
• Invalid command line parameters
• Excel file creation failures
• Template file corruption or incompatibility

Logging

When enabled with the -log flag, the application creates timestamped log files:

jira-spillover-chart-YYYYMMDD-HHMMSS.log

Logs include:

• Parameter validation and file processing status
• TSV parsing progress and statistics
• Excel file creation progress
• Error messages and warnings
• Execution timing information

Performance considerations

• Processing time depends on TSV file size and number of records
• Large datasets (>10,000 rows) may take several minutes to process
• Memory usage scales with input file size
• Recommended to use -debug flag for large files to monitor progress
• Patching XLSX files to enable pivot cache update on opening is done in memory

Troubleshooting

Common issues

1. Input file not found

   • Ensure the TSV file exists at the specified path
   • Check file permissions and verify read access

2. Invalid TSV format

   • Verify file is properly tab-separated
   • Ensure first row contains expected column headers
   • Check for special characters or encoding issues

3. Excel file creation failed

   • Verify write permissions to output directory
   • Ensure output filename doesn't contain invalid characters
   • Check available disk space

4. Template file issues

   • Verify template file exists and is a valid Excel file
   • Ensure template file is not open in Excel
   • Check template file permissions

5. Date formatting problems

   • Verify date columns contain valid yyyy-mm-dd format
   • Check for missing or malformed date values
   • Enable -debug flag to see date parsing details

Debug information

The application provides detailed progress information when using -debug flag:

• Input file validation and statistics
• TSV parsing progress and row counts
• Excel file creation progress
• Template processing status
• Data conversion and formatting details

All debug and error information is logged to timestamped files when -log is enabled.

Contributing

Contributions to improve this tool are welcome! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes to the Go source code or documentation
4. Test with sample data and various input scenarios
5. Submit a pull request with a clear description of the improvements

Please ensure your changes maintain compatibility with existing TSV formats and follow Go best practices.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses.

For the purposes of attribution please use https://www.linkedin.com/in/andrewnewbury

Copyright (C) 2025 Andrew Newbury

Support

This tool is unsupported and may cause objects in mirrors to be closer than they appear etc. Batteries not included.

It is suggested that you test this tool in a non-production environment to ensure it meets your needs.