gh-metrics

Aggregate the per-issue state-file timestamps and GitHub close-times into the metrics teams ask for during retros and planning.

When to use

• Retro / planning: "how did we do last sprint", "what's our throughput"
• Investigating bottlenecks: "why are issues piling up in in-review"
• Forecasting: "if we keep this velocity, when do we ship the milestone"

Inputs

gh-metrics [--days <n>] [--format text|json] [--milestone <number>]

Flag	Default	Effect
--days	30	Lookback window for closed-issue + transition data.
--format	text	text for human reading, json for piping (one record per issue).
--milestone	none	Restrict to issues attached to a specific milestone.

What it computes

1. Time-in-status (median + p90)

For each gate transition, read the per-issue state file (~/.cache/gh-pms/state/<owner>-<repo>.json) for last_transition_at per status. Compute time-in-status per issue, then aggregate:

2. Gate failure rate

A "gate failure" = a transition that bounced back to a prior status (e.g. in-review → in-progress after Needs Edits). Read the state file's transition history per issue:

3. Throughput

Count issues closed in the lookback window, optionally weighted by effort:*:

Issues without an effort:* label don't contribute to story-point totals (so missing data doesn't inflate the metric — they show up in raw count only).

4. Severity mix

Distribution of severity for issues SHIPPED in the window — reveals whether the team is firefighting or building:

A high Critical/High ratio in successive windows is a smell — surface it for the user.

5. Milestone progress + ETA

If --milestone <number> is set, also include:

For an in-flight milestone with the throughput above, project an ETA using the daily rate.

Implementation notes

• lib/gh-metrics.sh is the data layer; the skill drives it. The script reads:
  1. Local state files (transitions + timestamps)
  2. gh issue list --state closed --search "closed:>$DATE" for closures the local file may have missed
  3. gh api repos/$REPO/milestones for milestone progress
• All output is computed at runtime — no metric is cached longer than 5 minutes (analytics need to be fresh)
• Story-point weights (S=1, M=3, L=5, XL=8) are a Fibonacci default; per-repo override goes in .github/gh-pms.yaml under metrics.effort_points

Cross-skill contract

• gh-status answers "where are we now"; gh-metrics answers "how have we been doing"
• The two never conflict: gh-status reads current state, gh-metrics reads transition history. Run both during retros.

Notes

• Out of scope: charts / dashboards (text + JSON output is the contract; pipe JSON to your favorite plotter)
• Out of scope: cross-repo aggregation (covered by #14 cross-repo plans once it lands)
• Caveat: state files are local. If multiple developers work on the same issue from different machines, transition history fragments. Until a server-side state store is added, treat metrics as approximate, not authoritative.