Story: Sprint health charts

Goal
Status
Acceptance
Tasks
Plan
Decisions
Out of scope

This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Add a set of sprint health charts that render as PNG images on the sprint page, giving a one-glance view of how the sprint is progressing. Charts are generated by a Python data extractor that queries git history and the agile doc state machine, feeding CSVs into gnuplot scripts. The same data pipeline feeds into release notes generation.

Status

Field	Value
State	DONE
Parent sprint	Sprint 18
Now	Complete.
Waiting on	Nothing.
Next	None.
Last touched	2026-05-28

Acceptance

Python script scripts/sprint_metrics.py takes --sprint <N> and outputs CSV files under build/output/sprint_<N>/.
Gnuplot script scripts/plot_sprint_metrics.gnuplot reads CSVs and produces PNGs.
CMake target sprint_charts runs the extractor + gnuplot pipeline.
Sprint page (sprint.org) includes rendered PNGs via [[file:...]] links.
Charts survive site rebuilds (PNGs are committed or regenerated by CMake).
Pipeline is reusable for release notes.

Tasks

Task	State	Start	End	Description
Implement sprint health charts	DONE	2026-05-26	2026-05-28	Write Python data extractor, gnuplot scripts, CMake target, and wire PNGs into sprint page.

Plan

Charts

Two multi-panel charts combine all metrics into fewer images — one for activity, one for progress.

Chart A: Sprint Activity (3-panel)

Combines PR volume, commit granularity, and line churn in a single vertical stack:

Panel	Metric	Format	Source	Signal
Top	PRs & Commits per Day	Dual-axis bar (PRs left, commits right)	`git log --merges`, `git shortlog -sn`	PR velocity; commits/PR ratio reveals bloated PRs
Middle	Commits per PR	Scatter plot — one point per PR	`gh pr view --json commits` for each merged PR	Too many commits per PR = messy history, scope creep
Bottom	Daily Line Churn	Stacked bar (added green, deleted red)	`git diff --stat` bucketed by commit date	Build vs refactor signal; zero days = blocker

Chart B: Sprint Progress (2-panel)

Combines story burndown and PR cycle time:

Panel	Metric	Format	Source	Signal
Top	Cumulative Stories Done	Line chart — days on X, cumulative count on Y	`git log -p` over `doc/agile/versions/v0/sprint_N/`, grep STARTED→DONE transitions	Burndown: is the sprint on track?
Bottom	PR Cycle Time	Bar chart — one bar per PR, height = hours from open to merge	`gh pr view --json createdAt,mergedAt` per merged PR	Review bottlenecks: long bars = problem

Data Pipeline

git log + gh API  ──→  sprint_metrics.py  ──→  CSV files  ──→  gnuplot  ──→  PNGs  ──→  sprint.org

The Python script:

Takes --sprint <N>, --start-date, --end-date (or auto-detects from sprint doc).
Queries git log for commit/merge data between those dates.
Queries doc state files for story/task transitions.
Calls gh pr view for cycle time of each PR merged in the range.
Writes one CSV per chart (sprint_activity.csv, sprint_progress.csv).

The gnuplot script:

Reads each CSV and produces a PNG under assets/images/sprint_<N>/.

The CMake target (sprint_charts):

Depends on Python3 and gnuplot being installed.
Outputs a warning with install instructions if they're missing.

Wire into sprint page

Each chart gets an entry in the sprint's * Health Review section or a dedicated * Charts section:

#+attr_html: :width 100%
proj:doc/agile/versions/v0/sprint_18/sprint_health_charts/assets/images/sprint_18/sprint_activity.png

#+attr_html: :width 100%
proj:doc/agile/versions/v0/sprint_18/sprint_health_charts/assets/images/sprint_18/sprint_progress.png

Decisions

Commits are bucketed by author date (not committer date) to match when work actually happened.
PR cycle time = mergedAt − createdAt. Weekends are not excluded — a PR open over a weekend correctly shows longer cycle time.
Story state transitions are detected by grepping git log -p for changes to the State row in * Status tables. This is noisy but works without a structured database.
CSV files use tab separators (gnuplot's default) for simplicity.

Out of scope

Live chart generation during the sprint (charts are generated once, on-demand, not continuously).
Team velocity / effort estimation (we don't use story points).
Contributor-level metrics per sprint (individual commit counts).
A full dashboard or web UI — charts are static PNGs embedded in the sprint doc.