agentleFS
jcesarperezjcesarperez/claude-em/.claude/skills/check-epic/SKILL.md

check-epic

Skill94 starsChanged 5 months agoMITView on GitHub

Evaluate the health of a Jira epic: definition quality, issue decomposition, and execution dynamics. Use whenever the user wants to assess epic health, identify risks, or get prioritized recommendations.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 11 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run this script using the Bash tool:

    line 11
  2. Very specific:

    If EPIC_KEY is not an Epic, the script exits with an error.

    line 18
  3. Distinctive:

    Before running the script, resolve the epic key:

    line 81
  4. Very specific:

    If the argument matches the pattern [A-Z]+-\d+ (e.g.

    line 83
  5. Distinctive:

    If multiple matches are found, list them and ask the user to confirm which one to use.

    line 89
  6. Distinctive:

    If no match is found, report it and stop.

    line 90
  7. Distinctive:

    Run the script with the resolved epic key.

    line 94
  8. Very specific:

    Run the three health analyses using the pre-computed metrics and the epic + child_issues data

    line 95
  9. Distinctive:

    If true, flag it in the snapshot — the epic status contradicts the child issue data

    line 173
  10. Distinctive:

    DO NOT analyze child issue descriptions

    line 251
  11. Distinctive:

    DO NOT invent data not present in the input

    line 252
  12. Distinctive:

    If data is missing (no due date, empty description), state it explicitly rather than skipping

    line 253
  13. Distinctive:

    Avoid generic statements like "improve communication" or "ensure alignment"

    line 254
  14. Distinctive:

    DO NOT flag or recommend assigning issues that are not yet in progress — it is the expected workflow for issues to remain unassigned until …

    line 255

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Tool

Run this script using the Bash tool:

bash .claude/skills/check-epic/scripts/fetch_epic.sh <EPIC_KEY> --json
  • EPIC_KEY: the Jira epic key (e.g. FBX-1234) — may be resolved from a phrase; see Epic Key Resolution below
  • If EPIC_KEY is not an Epic, the script exits with an error. Report the error to the user and stop.

The script outputs JSON with this structure:

{
  "fetched_at": "2026-04-14T10:00:00Z",
  "epic": {
    "key": "FBX-1234",
    "summary": "...",
    "status": "In Development",
    "statusCategory": "In Progress",
    "description": "plain text",
    "duedate": "YYYY-MM-DD or null",
    "created": "...",
    "updated": "...",
    "comments": [
      { "author": "Name", "created": "...", "body": "plain text" }
    ],
    "time_in_current_status": { "formatted": "Xd Yh Zm", "seconds": 0, "since": "..." }
  },
  "metrics": {
    "total": 0,
    "done": 0,
    "in_progress": 0,
    "todo": 0,
    "blocked": 0,
    "pct_done": 0.0,
    "assignees": ["Name"],
    "assignee_count": 0,
    "closed_last_7d": 0,
    "created_last_7d": 0,
    "stale_in_progress": [{ "key": "FBX-X", "summary": "...", "time_in_status": "Xd Yh Zm" }],
    "unassigned_in_progress": ["FBX-X"],
    "days_until_due": 0,
    "epic_status_stale": false,
    "median_cycle_time_days": 0.0,
    "high_cycle_time_issues": [{ "key": "FBX-X", "summary": "...", "cycle_time_days": 0.0, "cycle_time_formatted": "Xd Yh Zm" }]
  },
  "child_issues": [
    {
      "key": "FBX-1235",
      "issuetype": "Story",
      "summary": "...",
      "status": "In Progress",
      "statusCategory": "In Progress",
      "assignee": "Name or null",
      "num_subtasks": 0,
      "duedate": "YYYY-MM-DD or null",
      "created": "...",
      "updated": "...",
      "time_in_current_status": { "formatted": "Xd Yh Zm", "seconds": 0, "since": "..." },
      "cycle_time": { "in_progress_at": "...", "done_at": "...", "seconds": 0, "days": 0.0, "formatted": "Xd Yh Zm" }
    }
  ]
}

Instructions

Epic Key Resolution

Before running the script, resolve the epic key:

  • If the argument matches the pattern [A-Z]+-\d+ (e.g. FBX-1234), use it directly.
  • Otherwise, treat it as a search phrase and search Jira for epics with a matching summary. Use this tool priority:
    1. jira skill — invoke /jira with JQL: issuetype = Epic AND summary ~ "<phrase>" ORDER BY created DESC
    2. CLI — jira issue list --jql 'issuetype = Epic AND summary ~ "<phrase>"'
    3. Batch — REST API calls via bash
    4. MCP — searchJiraIssuesUsingJql as last resort
  • If multiple matches are found, list them and ask the user to confirm which one to use.
  • If no match is found, report it and stop.

Analysis steps

  1. Run the script with the resolved epic key; stop and report the error if it fails
  2. Run the three health analyses using the pre-computed metrics and the epic + child_issues data
  3. Produce the structured report

Scoring Rubrics

Definition Health

Evaluate epic description + comments. Assess each criterion:

  • ✅ clearly present and specific
  • ⚠️ present but vague or incomplete
  • ❌ absent
#CriterionWhat counts as ✅
1Clear and testable goalDescribes what will be true when done, not just what will be built
2Success metrics / acceptance criteriaMeasurable outcomes or explicit done conditions
3Scope boundariesExplicit in-scope / out-of-scope statements
4Dependencies identifiedNamed teams, systems, or issues that are external blockers
5Rollout strategyFeature flags, phased rollout, migration plan
6ObservabilityDashboards, alerts, logs, or metrics named

Score:

  • 🟢 ≥4 criteria ✅
  • 🟡 2–3 ✅, or majority ⚠️
  • 🔴 ≤1 ✅, or description is empty

Decomposition Health

Evaluate issue list structure using summaries, types, and counts. Do NOT analyze issue descriptions.

#CriterionWhat counts as ✅
1CoverageIssue summaries collectively address all stated scope items; no major scope items untracked
2GranularityIssues are roughly similar in scope; no oversized items (num_subtasks > 5); median_cycle_time_days ≤ 7 when available
3Issue countAt least one issue per major scope item; not zero, not a single monolithic issue

Score:

  • 🟢 All ✅ or at most 1 ⚠️, no ❌
  • 🟡 1–2 ⚠️, no ❌
  • 🔴 Any ❌, or metrics.total == 0

Execution Health

Evaluate four signals, then derive overall state:

Velocity (use metrics.closed_last_7d):

  • Active: closed_last_7d > 0
  • Slow: closed_last_7d == 0 AND in_progress > 0
  • Stalled: closed_last_7d == 0 AND in_progress == 0

WIP pressure (use metrics.in_progress / metrics.total):

  • Healthy: in_progress / total ≤ 0.30 OR in_progress ≤ 2
  • High: in_progress / total > 0.30 AND in_progress > 2

Bottlenecks (use metrics.stale_in_progress and metrics.blocked):

  • Flag each issue in stale_in_progress (stuck ≥ 7d); issues ≥ 14d are critical
  • Flag each issue in blocked

Unassigned in-progress (use metrics.unassigned_in_progress):

  • Flag any in-progress issue with no owner — active work without an assignee is a delivery risk

Cycle time (use metrics.median_cycle_time_days and metrics.high_cycle_time_issues; skip entirely if null — not enough completed issues):

  • Healthy: median_cycle_time_days ≤ 5
  • At Risk: 5 < median_cycle_time_days ≤ 10, or any high_cycle_time_issues (> 2× avg and > 5d)
  • Critical: median_cycle_time_days > 10

Due date (use metrics.days_until_due and metrics.pct_done):

  • Evaluate overdue cases first (days_until_due < 0):
    • 🔴 days_until_due < 0 AND pct_done < 100 — overdue with open work remaining
    • ⚠️ days_until_due < 0 AND pct_done == 100 — past due date but all issues done; delivery timing unknown (epic may have finished on time but date was never updated)
  • Then evaluate upcoming deadline risk:
    • 🔴 days_until_due < 14 AND pct_done < 70
    • 🟡 days_until_due < 30 AND pct_done < 50
    • 🟢 otherwise, or days_until_due is null

Epic status staleness (use metrics.epic_status_stale):

  • If true, flag it in the snapshot — the epic status contradicts the child issue data

Overall execution state:

  • 🟢 Healthy: velocity Active, WIP Healthy, no bottlenecks or unassigned in-progress, due date 🟢, cycle time Healthy or null
  • 🟡 At Risk: any of — Slow velocity, High WIP, ≥1 stale in-progress, any unassigned in-progress, due date 🟡, due date ⚠️ (overdue but complete), cycle time At Risk
  • 🔴 Stalled: velocity Stalled, OR ≥2 issues stuck > 14d, OR due date 🔴 (overdue with open work, or upcoming with pct_done < 50), OR cycle time Critical

Output Format

Return ONLY this structure:


📊 Epic Snapshot — KEY: Summary

  • Total: X issues (X Done · X In Progress · X To Do[· X Blocked])
  • Completion: X% (X/X)
  • Assignees: X
  • Epic status: "Status" — in this status for Xd (since YYYY-MM-DD)[⚠️ Likely stale: X issues in progress/done but epic is "To Do"]
  • Closed last 7 days: X | Created last 7 days: X
  • Median cycle time: X.Xd (N done issues) | Not enough data
  • Due date: YYYY-MM-DD (X days remaining) | No due date set

🧠 Definition Health — 🟢 / 🟡 / 🔴

  • ✅/⚠️/❌ Clear goal: one-line assessment
  • ✅/⚠️/❌ Success criteria: one-line assessment
  • ✅/⚠️/❌ Scope boundaries: one-line assessment
  • ✅/⚠️/❌ Dependencies: one-line assessment
  • ✅/⚠️/❌ Rollout strategy: one-line assessment
  • ✅/⚠️/❌ Observability: one-line assessment

🧩 Decomposition Health — 🟢 / 🟡 / 🔴

  • ✅/⚠️/❌ Coverage: one-line assessment (cite missing scope items if ⚠️/❌)
  • ✅/⚠️/❌ Granularity: one-line assessment
  • ✅/⚠️/❌ Issue count: one-line assessment

⚙️ Execution Health — 🟢 Healthy / 🟡 At Risk / 🔴 Stalled

  • Velocity: Active / Slow / Stalled (X closed last 7d)
  • WIP: X in progress / X total (XX%)
  • Bottlenecks: KEY stuck Xd, KEY stuck Xd (critical: KEY stuck Xd) | None
  • Blocked: X issues | None
  • Unassigned in-progress: KEY, KEY | None
  • Cycle time: X.Xd median — 🟢 Healthy / 🟡 At Risk / 🔴 Critical | Not enough data
  • Cycle time outliers: KEY Xd (Xx median), KEY Xd | None
  • Due date: YYYY-MM-DD (X days remaining) — 🟢 On Track / 🟡 At Risk / 🔴 Critical | YYYY-MM-DD (Xd overdue, work still open) — 🔴 Overdue | YYYY-MM-DD (Xd overdue, all issues done) — ⚠️ Past due, delivery timing unknown | No due date set
  • Key risks: bullet list
  • Likely causes: bullet list

🧭 Summary

Overall: 🟢/🟡/🔴 · Definition: 🟢/🟡/🔴 · Decomposition: 🟢/🟡/🔴 · Execution: 🟢/🟡/🔴

  • 3–6 bullets: current state · main risk · main blocker

🎯 Recommendations

  1. [Verb] Specific concrete action
  2. ... (3–6 items, ordered by impact and urgency)

Style Guidelines

  • Cite issue keys, percentages, and durations — no vague observations
  • Trust child issue data over epic status when they conflict (metrics.epic_status_stale)
  • Mine epic comments for blockers, decisions, and context not visible in the issue list
  • Child issue summaries are fair game; issue descriptions are not
  • Be concise and direct — EM tone, no fluff
  • Prioritize signal over completeness

Constraints

  • DO NOT analyze child issue descriptions
  • DO NOT invent data not present in the input
  • If data is missing (no due date, empty description), state it explicitly rather than skipping
  • Avoid generic statements like "improve communication" or "ensure alignment"
  • DO NOT flag or recommend assigning issues that are not yet in progress — it is the expected workflow for issues to remain unassigned until they move to the "In Progress" status category

Goal

Help an Engineering Manager quickly answer:

"Is this epic under control, what are the risks, and what should I do next?"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.