| name | agile:epic:priority |
| description | Analyze epics and rank by implementation priority using 6-factor weighted scoring from epic, feature, and task data. Factors include task completion (6-state markers), artifact readiness (epic + feature level), dependency readiness, journey progress, implementation readiness (implement skill prerequisites), and blocking value. |
| user-invocable | true |
| disable-model-invocation | false |
Epic Priority Dashboard
Overview
Analyze epics in agile/epics/ and display a two-table priority dashboard: recently completed and a unified priority backlog ranked by a
6-factor weighted composite score.
Invocation
- Command:
/agile:epic:priority
Execution Steps
Step 1: Gather Data
Run the data extraction script:
bash .claude/skills/agile-epic-priority/scripts/agile-epic-priority.sh
This outputs pipe-delimited rows with header:
EPIC_ID|STATUS|DEPENDENCIES|FEATURES_COUNT|TASK_COMPLETED|TASK_INPROGRESS|TASK_BLOCKED|TASK_SKIPPED|TASK_PENDING|TASK_TOTAL|ARTIFACT_FILES|ARTIFACT_POSSIBLE|JOURNEY_CHECKED|JOURNEY_TOTAL|IMPL_MET|IMPL_TOTAL|RESOLVED_DEPS
| Field | Description |
|---|
| EPIC_ID | Directory name (e.g. 096-cross-module-build-fix) |
| STATUS | Normalized status from epic.md (DONE variants normalized to COMPLETED) |
| DEPENDENCIES | Comma-separated 3-digit epic IDs this epic depends on. The script first checks for the standardized **Dependencies**: metadata field. If not found, it falls back to multi-pattern extraction (backward compatibility). |
| FEATURES_COUNT | Number of feature subdirectories |
| TASK_COMPLETED | Count of [X] (or [x]) task markers across feature tasks.md files |
| TASK_INPROGRESS | Count of [W] and [-] task markers (work in progress + partial) |
| TASK_BLOCKED | Count of [B] task markers |
| TASK_SKIPPED | Count of [S] task markers |
| TASK_PENDING | Count of [ ] task markers |
| TASK_TOTAL | Sum of all task markers (completed + inprogress + blocked + skipped + pending) |
| ARTIFACT_FILES | Count of artifacts found: epic-level (plan.md, checklist.md) + feature-level (spec.md, tasks.md) |
| ARTIFACT_POSSIBLE | Maximum possible artifacts: 2 (epic-level) + features x 2 (feature-level) |
| JOURNEY_CHECKED | [x] count in Progress Tracking table (Plan/Tasks/Implement/Validate) |
| JOURNEY_TOTAL | Total checkboxes in Progress Tracking table |
| IMPL_MET | Number of implementation prerequisites met (see Implementation Readiness factor) |
| IMPL_TOTAL | Total implementation prerequisites checked |
| RESOLVED_DEPS | Each dependency with resolved status, e.g. 095:COMPLETED,087:IMPLEMENTING. Empty if no dependencies |
6-State Task Markers
The script recognizes all 6 task marker states used by the agile pipeline (agile:epic:plan and agile:epic:implement):
| Marker | State | Counted In |
|---|
[X] | Completed | TASK_COMPLETED |
[x] | Completed | TASK_COMPLETED |
[W] | In Progress | TASK_INPROGRESS |
[-] | Partial | TASK_INPROGRESS |
[B] | Blocked | TASK_BLOCKED |
[S] | Skipped | TASK_SKIPPED |
[ ] | Pending | TASK_PENDING |
Step 2: Classify Epics
Parse each row and classify into two buckets based on the STATUS field:
| Bucket | Status Matches | Rule |
|---|
| Completed | Status begins with COMPLETED OR status is SUPERSEDED OR VALIDATED OR ABANDONED | Work is finished. The script normalizes DONE/VALIDATED/REMOVED/ABANDONED → COMPLETED before output. SUPERSEDED epics are work that was superseded by another epic. |
| Backlog | Everything else: IMPLEMENTING, IMPLEMENTED, INCOMPLETE, BLOCKED, PLANNING, ACTIVE, UNKNOWN, NO_SPECIFICATION, empty | All non-completed work, ranked by score |
Step 3: Calculate Priority Scores (Backlog only)
For each Backlog epic, calculate a priority score (0-100) using six weighted factors:
| Factor | Code | Weight | Source | Calculation |
|---|
| Task Completion | T | 20% | Script: TASK_COMPLETED, TASK_SKIPPED, TASK_TOTAL | TASK_COMPLETED / (TASK_TOTAL - TASK_SKIPPED) * 100. Skipped tasks are excluded from both numerator and denominator (per agile:epic:implement status-tracker). If effective total = 0, score = 0 |
| Artifact Readiness | R | 20% | Script: ARTIFACT_FILES, ARTIFACT_POSSIBLE | ARTIFACT_FILES / ARTIFACT_POSSIBLE * 100. Includes epic-level (plan.md, checklist.md) and feature-level (spec.md, tasks.md) per agile:epic:plan output. If ARTIFACT_POSSIBLE = 0, score = 0 |
| Dependency Readiness | D | 30% | Script: RESOLVED_DEPS | For each dep in RESOLVED_DEPS, status starting with COMPLETED = met, otherwise = unmet. Score = met_deps / total_deps * 100. No dependencies = 100 |
| Journey Progress | J | 15% | Script: JOURNEY_CHECKED, JOURNEY_TOTAL | JOURNEY_CHECKED / JOURNEY_TOTAL * 100. If JOURNEY_TOTAL = 0, score = 0 |
| Implementation Readiness | I | 5% | Script: IMPL_MET, IMPL_TOTAL | IMPL_MET / IMPL_TOTAL * 100. Measures whether the epic has all prerequisites for /agile:epic:implement. If IMPL_TOTAL = 0, score = 0 |
| Blocking Value | B | 10% | Reverse dependency scan | Count non-completed epics whose DEPENDENCIES field contains this epic's ID. Score = count * 20, capped at 100 |
Score formula: Score = (T * 20 + R * 20 + D * 30 + J * 15 + I * 5 + B * 10) / 100
Breakdown string: Format as T:{t} R:{r} D:{d} J:{j} I:{i} B:{b} where each value is the factor's 0-100 score rounded to nearest
integer.
Implementation Readiness Checks (I Factor)
The I factor measures whether an epic meets the prerequisites for the agile:epic:implement skill. The script checks:
| # | Prerequisite | What It Checks |
|---|
| 1 | epic.md exists | Core specification file at epic root |
| 2 | plan.md exists | Strategic plan at epic root (generated by agile:epic:plan) |
| 3 | checklist.md exists | Verification gates at epic root (generated by agile:epic:plan) |
| 4 | Feature Workflow DAG present | ## Feature Workflow section in epic.md (canonical dependency source) |
| 5 | All features have spec.md | Every feature directory contains spec.md (only checked if features > 0) |
| 6 | All features have tasks.md | Every feature directory contains tasks.md (only checked if features > 0) |
Score = checks_met / checks_total * 100. Epics without features are checked on prerequisites 1-4 only (4 total).
Epics with features are checked on all 6 (6 total).
An I score of 100 means the epic is fully ready for /agile:epic:implement execution.
Computing Blocking Value (B)
To compute factor B for a given epic:
- Collect all Backlog epics' DEPENDENCIES fields
- Count how many of those dependency lists contain the current epic's ID (exact 3-digit match)
- Multiply count by 20, cap at 100
Edge Cases
| Scenario | Handling |
|---|
| Epic has no feature folders | T=0, R based on epic-level only, J=0, I checks 1-4 only |
| Epic has no tasks.md at all | T=0, J=0 — early-stage epic scores low naturally |
| Feature folder exists but empty | That feature contributes 0 to T, lowers R and I |
| BLOCKED status | Low T/J push it down naturally |
| PLANNING status | Low T/J, may score on R/D/B/I |
| All tasks skipped | T=0 (effective total = 0), no division by zero |
Step 4: Generate Rationale (Top 3 only)
For the top 3 scoring Backlog epics, the script generates a dynamic rationale from the score breakdown.
The rationale highlights the strongest contributing factors in priority order:
- Blocking value (B >= 40): "blocks N epics" — why this epic matters to others
- Dependency readiness (D): "all deps met" or "N% deps met" — can work begin?
- Task progress (T > 30): "N% tasks done" or "N% complete" — how far along?
- Implementation readiness (I >= 50): "impl-ready" or "N% impl-ready" — can implement run?
- Artifact readiness (R >= 60, as fill): "N% artifacts ready" — planning completeness
Examples of dynamic rationale:
- "blocks 2 epics, all deps met, 75% tasks done"
- "all deps met, 80% complete, impl-ready"
- "67% deps met, 45% tasks done, 83% impl-ready"
- "all deps met, impl-ready, 90% artifacts ready"
The rationale is generated dynamically from scores — never hardcoded to specific epic IDs.
Step 5: Render the Dashboard
Output the following markdown, filling in data from classification and scoring:
Summary
## Epic Priority Dashboard
### Summary
- **Total Epics**: {count}
- **Completed**: {count} ({percent}%)
- **Backlog**: {count}
Table 1 — Recently Completed (Last 5)
Show the 5 completed epics with the highest epic number (highest = most recent). Ordered descending by epic number.
### Recently Completed
| # | Epic | Status |
|-----|-----------|----------|
| 1 | {epic_id} | {status} |
| ... | ... | ... |
Table 2 — Priority Backlog
Show ALL backlog epics, ranked by priority score (highest first).
If an epic has any unmet dependency (any dep in RESOLVED_DEPS whose status does NOT start with COMPLETED), prepend [!] to the Status
cell.
The Deps column shows dependencies with short status labels: done (COMPLETED), active (IMPLEMENTING/ACTIVE/IMPLEMENTED), plan (
PLANNING), block (BLOCKED). Example: 095(done), 087(active). Empty if no dependencies.
### Priority Backlog
| Rank | Epic | Status | Deps | Features | Score | Breakdown |
|------|-----------|------------------------|--------|------------|---------|-------------------------------------|
| 1 | {epic_id} | {status or [!] status} | {deps} | {features} | {score} | T:{t} R:{r} D:{d} J:{j} I:{i} B:{b} |
| ... | ... | ... | ... | ... | ... | ... |
If no backlog epics exist, output: *No backlog epics.*
Recommendation
### Recommendation
| Rank | Epic | Score | Rationale |
|------|-----------|---------|-------------------------|
| 1 | {epic_id} | {score} | {rationale from Step 4} |
| 2 | {epic_id} | {score} | {rationale from Step 4} |
| 3 | {epic_id} | {score} | {rationale from Step 4} |
If fewer than 3 backlog epics exist, show only what's available.
Optional: Dependency Graph Mode
When invoked with --deps argument:
- Run the standard data extraction
- Instead of the priority table, render an ASCII dependency graph:
098-dao-adapter-type-migration
└── 095-complete-adapter-migration (COMPLETED)
└── 093-service-layer-dao-migration (COMPLETED)
097-entity-name-disambiguation
(no dependencies)
- Show only backlog epics and their dependency chains
Pipeline Alignment
This skill integrates with the agile epic pipeline:
| Pipeline Stage | Skill | Priority Factor Connection |
|---|
| Brainstorm | agile:epic:brainstorm | design.md existence feeds artifact readiness (R) |
| Plan | agile:epic:plan | plan.md, checklist.md, Feature Workflow DAG feed R and I |
| Implement | agile:epic:implement | I factor directly measures implement prerequisites |
| Progress | agile:epic:progress | 6-state task markers feed T factor with proper skip handling |
