jira-changelog

Files (2)

• SKILL.md
• jira-changelog.md · references/

SKILL.md (first lines)

# Jira changelog and sprint replay

Prereq: `ad-doctor` row `jira / jira auth` is not `fail`. Failing → print its hint, STOP.

1. Once per Jira instance: `ad-jira fields --like sprint` and `ad-jira fields --like point`; then `ad-jira fields --pin` (stores the Sprint and Story Points field ids in the global config). Two plausible point fields with different meanings → `friction-log` type `missing-info`. STOP. Why the ids are not the same on two instances: `references/jira-changelog.md` §Field ids are per instance.
2. First run of a new JQL: pass `--stats` and read `requests` in the meta before widening that JQL or dropping `--since`. Hundreds of requests on the narrow form means the wide form will hit the budget; narrow the JQL instead of raising `--max-requests`. The defaults, the flags and what a budget stop looks like: `references/jira-changelog.md` §Limits and budgets.
3. Field history: `ad-jira changelog <KEY> [<KEY>…] --fields status,Sprint,"Story Points" [--since 2025-01-01]`, or `--jql "<JQL>"` instead of keys. Columns: key, changelog_id, created_utc, author, field, field_id, from_id, from_str, to_id, to_str. Use `*_id` for Sprint and status (stable ids), `*_str` for points.
4. `partial: true` in the meta is a command: run the meta's `resume` line once, exactly as printed — never a hand-edited version of it, and note that it deliberately drops the `--max-requests` / `--max-seconds` that stopped the run. Every issue that finished is cached, so the rerun asks Jira only for what is missing. Still `partial: true` → quote the meta's `hint` (it names the one thing to do about this `reason`) in a `friction-log` type `missing-info` with `reason`, `rows_written`, `issues_complete` and `issues_incomplete_count`. STOP. What each `reason` means and which of them a rerun cannot fix: `references/jira-changelog.md` §Partial results.
5. Never pass `--allow-partial` to make a refusal go away. Pass it only when the ticket says an approximate answer is acceptable, and then write `partial: true` and `issues_incomplete_count` into the findings sentence that carries the number. It exists on `sprint-replay` only; a partial `changelog` is rerun, never waved through.
6. Sprint numbers: `ad-jira sprints --board <jira_board_id> --state closed` to find the id, then
   `ad-jira sprint-replay --sprint <id> --board <jira_board_id> --jql "project = <KEY> AND updated >= '<sprint start - 1d>'"`.
   The `--jql` widening is required to see punted issues: JQL `sprint = <id>` no longer matches issues removed from the sprint. What a Sprint value actually holds: `references/jira-changelog.md` §Sprint field semantics.
7. `sprint-replay` exits 2 on a changelog that came back short, and prints the same `resume` command. Rerun it once; still short → step 4's `friction-log`. STOP. Never compute over a short history to get a number out.
8. Read `summary`: `committed_points` (estimate at sprint start), `completed_points` (credited at close by default; pass `--points-at commit` only when the ticket says so, and state the choice in findings), `added`, `punted`, `re_estimated`, `estimated_mid_sprint`, `carried_over`, `reopened`, `completed_in_another_sprint`. `provisional: true` means the sprint is still active. How each number was derived, and which are credited when: `references/jira-changelog.md` §Replay rules.
9. Cross-check only when asked: `--compare-sprintreport`. A non-zero delta lists `keys_only_in_report` / `keys_only_in_replay`; Jira's Sprint Report is a hint, the replay rows are the evidence.
10. The cache is on for every `--jql` run and is what makes step 4's rerun cheap; `cached` and `fetched` in the meta say what it saved. Use `--refresh` only after a `friction-log` has recorded a history the cache cannot have (the issue's `updated` did not move but its history did — a re-index). Never `--no-cache` in a normal run. Inspect or reset it with `ad-jira cache --stats` and `ad-jira cache --clear`. Where it lives and what it keys on: `references/jira-changelog.md` §Cache.
11. `rule: 6` → script over `path`, never read rows. `ok: false` without `partial: true` → fix once from `hint`; second failure → `friction-log` type `tool-error`.
12. `state-update` with the paths. Hand off → `pbip-projection` when comparing to a report (it leads on to `uat-report-visual`, which needs the projection first), `confluence-publish` when documenting, else `router`.

§ When a result looks impossible rather than merely wrong: `references/jira-changelog.md` §Known limits — the changelog does not record everything, and Cloud and Data Center differ (§Flavor). Each step above points at the one section it needs.

From agentchieflou/this-next-please, MIT.

More from agentchieflou/this-next-please