THIS DOCUMENT IS AN ALPHA VERSION/WORK IN PROGRESS sections to be updated are prefixed with "..INSERT:"

A tool to generate comprehensive sprint statistics focused on spillover for assignees, work items, story points, completed items, spillover items, and percentage ratios for analysis.

..INSERT: update TOC...

• Why spillover matters
• What does jira-spillover-stats do?
• Key features
  • Who should use this tool
  • Use cases
  • Project structure
• Prerequisites
• Set up
  • PowerShell
  • Windows command line
  • Linux/WSL
• Build the application
  • Windows
  • Linux/macOS
  • Building from source
  • Testing
• Usage
  • Basic execution
  • Parameters
  • Examples
  • Append mode feature
  • Automated execution
• Output format
• Interpreting results
  • Key metrics to review
  • Common patterns and what they mean
  • Recommended actions
• How jira-spillover-stats works
  • Jira field mappings
• Error handling
• Logging
• Performance considerations
• Troubleshooting
  • Common issues
  • Debug information
• Contributing
• License
• Support

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 creating a TSV (tab-separated variable) output file of work items which have spilled over. The TSV file can be manipulated by Excel or similar tools to produce rich graphical reporting.

For an in-depth examination of why spillover matters, how to analyse it, and most importantly, what strategic approaches you can implement to reduce it, check out the blog post "Mastering agile spillover, analysis and strategic solutions".

• Queries Jira to collect historical sprint report data from the GreenHopper API endpoint to compute per-sprint metrics that emphasise spillover.
• Produces a tab-separated file (.tsv) with aggregated statistics per sprint.
• Can run interactively (prompts for missing parameters) or fully from the command line (non-interactive).
• Uses the historical sprint report (a snapshot at the time the sprint was closed) to accurately classify work items as completed, not completed, punted, or completed in another sprint.

• Command line interface with interactive fallback for missing parameters.
• Secure Authentication using a file-based API token.
• Comprehensive Logging with an optional -log flag to create timestamped log files.
• Append Mode allows for the accumulation of data from multiple projects or over time into a single file.
• Project Validation ensures the project exists and is accessible before processing.
• TSV Output generates a tab-separated values file for easy import into spreadsheet applications.

• Agile teams looking to reduce their spillover rate
• Scrum Masters and Agile Coaches tracking team efficiency
• Development Team Leads identifying planning improvement opportunities
• Project Managers monitoring delivery predictability

• Use with sprint reviews to help identify continuous improvement opportunities
• Combine multiple project spillover data for portfolio analysis
• Building long-term trend data for retrospectives
• Automated reporting pipelines that accumulate data over time

└── jira-spillover-stats/
    ├── .gitignore
    ├── LICENSE                         # User license
    ├── README.md                       # The file you're reading now :D
    ├───.copilot
    │   └── copilot-instructions.md     # Copilot instructions
    ├── build/
    │   ├── jira-spillover-stats.exe       # Windows executable
    │   ├── jira-spillover-stats-android64 # Android executable
    │   ├── jira-spillover-stats-linux     # Linux executable
    │   └── jira-spillover-stats-macos     # macOS executable
    ├── go/
        ├── build.sh                    # Unix/Linux build script
        ├── build.bat                   # Windows build script
        ├── go.mod                      # Go module definition
        ├── jira-spillover-stats.go     # Go application source code
        ├── resource.syso               # Dynamically created by go generate
        └── versioninfo.json            # Windows resource definition
    

1. Jira API token: You need a valid Jira API token.
2. Network access: A connection to your Jira instance is required.
3. Project access: You must have sufficient permissions to view the target Jira project.

1. Clone or download the source code.
2. Create a Jira API token. See Manage API tokens for your Atlassian account.
3. Create a text file (e.g., Jira-API-token.txt) in a secure location.
4. Add a single line to this file with your credentials in the format: your-email-address:your-api-token.
5. Secure the API token file using one of the following methods.

icacls Jira-API-token.txt /inheritance:r /grant:r "$($env:USERNAME):(F)"

icacls Jira-API-token.txt /inheritance:r /grant:r "%USERNAME%:(F)"

chmod 400 Jira-API-token.txt && chown $(whoami) Jira-API-token.txt

Precompiled binaries are supplied in the build/ directory, or you can build your own.

cd go
build.bat

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

The build scripts use go build. To build for a specific platform:

# Build for Windows
go build -o jira-spillover-stats.exe

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

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

# Build for Android64
GOOS=android GOARCH=arm64 CGO_ENABLED=0 go build -o jira-spillover-stats-android64 jira-spillover-stats.go

NB requires https://github.com/josephspurrier/goversioninfo for embedding Windows file properties in the executable.

...INSERT:write up how to get/use goversioninfo here...

./jira-spillover-stats -help

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

jira-spillover-stats.exe

All command-line parameters:

jira-spillover-stats.exe [-TokenFile token_file_path] [-url jira_base_url] 
    [-project project_key] [-outputFile filename] [-storypoints customfield_aabbcc] 
    [-sprint "sprint_name"] [-append] [-log] [-debug]
    [-? | /? | --help | -help]

• -tokenFile path and filename of your Jira API token (email-address:api-token)
• -url Jira base URL (e.g., https://my-company.atlassian.net)
• -project Jira project key (e.g., EXPD)
• -outputFile optional name for output file (default: issues_output.tsv)
• -storyPoints customfield_10041 specify the field name for story points, this field name is specific to your Jira implementation
• -sprint report on a specific sprint
• -append append to existing output file instead of overwriting
• -log enable logging to a file
• -debug enable detailed debugging to the console and log file
• -? | /? | --help | -help show help message

"storypoints" this custom field name is specific to your Jira implementation, obtain the correct field name from your Jira administrator or lookup via https://my-company.atlassian.net/rest/api/latest/field

Command line with all parameters: ...INSERT: add story points field...

jira-spillover-stats.exe -tokenfile my-api-key.txt -url https://my-company.atlassian.net -project EXPD -outputfile spillover_stats.tsv -append -log -debug

Interactive mode (no parameters):

jira-spillover-stats.exe

The -append flag enables the accumulation of data across multiple runs.

• Benefits: Build historical datasets, combine data from multiple projects, and perform incremental data collection.
• Header Management: Headers are automatically written only when creating new files. No duplicate headers are added when appending.

The command-line parameters allow you to run this application from a scheduler or a batch file.

rem Weekly scheduled task to append new spillover data
jira-spillover-stats.exe -project EXPD -outputfile monthly_spillover.txt -append -log

The application generates a tab-separated text file with the following columns:

• project
• sprint_id
• sprint
• start date
• end date
• goals
• unique assignees
• sprint items count
• sprint items unique parents
• sprint items story points
• completed item count
• completed unique parents
• completed story points
• spillover item count
• spillover unique parents
• spillover story points
• % spillover count
• % spillover unique parents
• % spillover story points

...INSERT: explain above metrics...

...INSERT: expand with details on how to interpret the key metrics from the output file...

...INSERT: expand to describe common data patterns and their potential causes....

...INSERT: expand suggested actions based on the analysis of the spillover data...

1. Initialization: The tool parses command-line flags. If required flags are missing, it enters interactive mode.

2. Project Validation: It validates that the project exists and is accessible via the /rest/api/3/project/{projectKey} endpoint.

3. Sprint Discovery: It fetches all closed sprints for the project by first finding the project's boards and then the sprints for each board.

4. Sprint Report Fetching: For each closed sprint, it fetches the historical sprint report using the GreenHopper API (/rest/greenhopper/1.0/rapid/charts/sprintreport). This provides an accurate snapshot of issue statuses at the time the sprint was closed.

   NB This API is used internally by Jira for sprint history, it is not an officially documented API call.

5. Data Processing: It converts the report data, categorizing issues as completed, not completed, punted, or completed elsewhere.

6. Statistics Calculation: It computes aggregate statistics for each sprint, including counts, story point totals, and spillover ratios.

7. Output: The final statistics are written to the specified .tsv file.

The application uses default field mappings that are standard for Jira Cloud. The story points field can be overridden via the command line.

• Story Points: customfield_10041 (configurable with -storypoints)

The application includes error handling for common issues such as network problems, authentication failures, invalid project keys, and file I/O errors.

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

jira-spillover-stats-YYYYMMDD-HHMMSS.log

Logs include:

• API request details
• Progress information
• Error messages and warnings
• Execution timing statistics

• ...
• Recommended execution frequency at the end of every sprint or for an entire program increment or set of increments
• This application has been designed to return thousands of issues over multiple years

1. Token file not found

   • Ensure the token file exists at the specified path
   • Check file permissions

2. Authentication failed

   • Verify your Jira credentials in the token file
   • Ensure the token file format is correct (email-address:token)
   • Check that the API token is still valid

3. Project not found

   • The project code might not exist
   • Check the project code spelling and case
   • Verify you have permission to view the project

4. API connection issues

   • Verify network connectivity to Jira
   • Check if you're behind a corporate firewall/proxy
   • Ensure the Jira URL is correct and accessible, try accessing it in a browser

5. No issues found

   • Check if the project has Story/Task/Bug issue types
   • Verify the date range (if specified) contains resolved issues
   • Ensure the project contains work items

6. Export file issues

   • Ensure you have write permissions to the target directory
   • Check that the output filename doesn't contain invalid characters
   • Verify the output directory exists (the tool creates files but not directories)
   • When using -append, ensure the existing file format matches

The tool provides detailed progress information including:

• Authentication source and validation
• Project validation results
• ...INSERT: review this section...
• API request progress and batch information
• Issue processing and with the optional '-debug' command line switch, display of each work item's sprint data during processing

All debug information is logged to timestamped log files for later analysis.

Contributions to improve this tool are welcome! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request with a clear description of the improvements

Please ensure your code follows existing style patterns and includes appropriate comments.

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

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.