agile-epic-priority

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:

1. Collect all Backlog epics' DEPENDENCIES fields
2. Count how many of those dependency lists contain the current epic's ID (exact 3-digit match)
3. 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:

1. Blocking value (B >= 40): "blocks N epics" — why this epic matters to others
2. Dependency readiness (D): "all deps met" or "N% deps met" — can work begin?
3. Task progress (T > 30): "N% tasks done" or "N% complete" — how far along?
4. Implementation readiness (I >= 50): "impl-ready" or "N% impl-ready" — can implement run?
5. 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:

1. Run the standard data extraction
2. 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)
   

3. 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