Documentation
EpicWarden
How to install, configure, and use EpicWarden on your own Jira site.
Getting started
EpicWarden adds a drift-tracking panel to every Epic in Jira. There's nothing to install or configure to start seeing it.
- Open any Epic. EpicWarden appears in the right sidebar, collapsed by default.
- On any issue that isn't an Epic, it shows a short message and does nothing else.
- With no configuration at all, it tracks drift by issue count, the default metric.
- A baseline locks automatically the first time the Epic moves into an "In Progress"-type status. You can also lock one manually at any time with "Lock Baseline Now."
- Once a baseline exists, a colour-coded badge shows on the Epic's collapsed row, before you even open the panel.
Settings & setup
Open Settings from the "Settings" button at the bottom of the panel. Most settings apply across the whole Jira site, not just the Epic you opened them from, except Story Points field and Spillover, which are scoped narrower. Scope is called out per setting below.
| Setting | Default | Scope | What it does |
|---|---|---|---|
| Track drift by | Issue count | Whole site | Measures drift by ticket count or by Story Points. |
| Story Points field | Auto-detected | Per project | Which custom field holds Story Points for that project. |
| Spillover Epic key | None | Per Epic | Where "Move to Spillover" sends drifted tickets. |
| Automatic spillover | Off | Per Epic | Moves new tickets to the Spillover Epic the moment they're added. |
| Amber threshold | 10% | Whole site | Drift % where the badge turns amber. |
| Red threshold | 25% | Whole site | Drift % where the badge turns red. |
| Cost per unit | Off (blank) | Whole site | Enables the financial exposure figure. |
| Currency symbol | £ | Whole site | Symbol shown next to cost figures. |
Tracking by Story Points
Switch "Track drift by" to Story points and EpicWarden finds the right custom field for that project automatically, the first time it's needed. No field ID required.
If it can't resolve one automatically, it's for one of two reasons:
- Two or more fields match. The panel shows a prompt naming each candidate field; pick the right one by name.
- None found. Set one manually under "Advanced: override Story Points field" in Settings, using the field's ID from Jira Settings → Issues → Custom fields.
If a resolved field turns out to be wrong, use "Reset to auto-detect" in the same Advanced section. This clears the saved choice so EpicWarden re-detects it on the next load.
Setting up Spillover
- Enter a Spillover Epic key (e.g.
TA-42). It must be a different Epic you have edit access to. - Tick "Automatically move new tickets to the Spillover Epic" if you want new tickets redirected the instant they're added, before they count as drift at all. This checkbox stays disabled until a Spillover Epic key is set.
Without automatic spillover, drifted tickets stay on the Epic and show up in the Audit Trail for manual review instead.
Thresholds and cost
Amber threshold must be lower than red threshold, or Settings won't save. Cost per unit is optional: leave it blank to hide the financial exposure figure entirely rather than showing a misleading cost of zero.
The "Reset thresholds & cost" button only resets amber/red thresholds, cost per unit, and currency symbol back to their defaults. It deliberately leaves Track drift by, Story Points field, and Spillover settings untouched, since those are real choices about how your team works, not generic defaults to snap back to.
Features
- Baseline Lock
- Snapshots the Epic's ticket count and Story Points the moment it needs one: automatically the first time the Epic moves into an "In Progress" status, or manually any time via "Lock Baseline Now." Re-baseline later with the same button; EpicWarden keeps a full history of every re-baseline, who did it, and any note attached.
- Drift Badge
- A colour-coded badge (green, amber, red) shows on the Epic's row itself, before you open it, and again inside the panel with the full baseline-versus-current breakdown. If the metric you're not tracking is worse than the one shown on the badge, a "Metrics disagree" warning explains the gap, so the badge is never the only thing you see.
- Financial Exposure
- Opt-in. Set a cost per issue or per Story Point in Settings, and EpicWarden shows what drift is actually costing: baseline cost, current cost, and the exposure between them, both in the panel and in exports.
- Proactive Alerts
- EpicWarden emails you automatically the moment drift crosses your configured threshold, in either direction, worsening or recovering. It always checks both issue count and Story Points and alerts on whichever is worse, so a scope increase can't be hidden by improving only the metric you happen to be tracking.
- Audit Trail
- Every ticket added to the Epic after its baseline is locked gets logged automatically: which ticket, who added it, when. Review the list in the panel, generate an audit email summarizing it (with the financial exposure, if configured), or export a full CSV report attached directly to the Epic: both metrics side by side, the cost breakdown, and every drifted ticket.
- Spillover
- Keeps a started Epic from growing past its baseline. Select drifted tickets in the panel and hit "Move to Spillover" to re-parent them onto your configured Spillover Epic, or enable automatic spillover in Settings to redirect new tickets the instant they're added, before they ever count as drift. Either way, EpicWarden posts a comment on the moved ticket explaining where it went and why.