ln-230-story-prioritizer

What this skill does

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

# Story Prioritizer

**Type:** L3 Worker
**Category:** 2XX Planning

Evaluate Stories using RICE scoring with market research. Generate consolidated prioritization table for Epic.

## Purpose & Scope

- Prioritize Stories AFTER ln-220 creates them
- Triage all Stories cheaply before doing deep research
- Research market size and competition only where it changes prioritization confidence
- Calculate RICE score for each Story
- Generate prioritization table (P0/P1/P2/P3)
- Output: docs/market/[epic-slug]/prioritization.md

## When to Use

**Use this skill when:**
- Stories created by ln-220, need business prioritization
- Planning sprint with limited capacity (which Stories first?)
- Stakeholder review requires data-driven priorities
- Evaluating feature ROI before implementation

**Do NOT use when:**
- Epic has no Stories yet (run ln-220 first)
- Stories are purely technical (infrastructure, refactoring)
- Prioritization already exists in docs/market/

---

## Input Parameters

| Parameter | Required | Description | Default |
|-----------|----------|-------------|---------|
| epic | Yes | Epic ID or "Epic N" format | - |
| stories | No | Specific Story IDs to prioritize | All in Epic |
| depth | No | Research depth (quick/standard/deep) | "standard" |

**depth options:**
- `quick` - 2-3 min/Story, 1 WebSearch per type
- `standard` - 5-7 min/Story, 2-3 WebSearches per type
- `deep` - 8-10 min/Story, comprehensive research

---

## Output Structure

```
docs/market/[epic-slug]/
└── prioritization.md    # Consolidated table + RICE details + sources
```

## Runtime Contract

**MANDATORY READ:** Load `references/planning_worker_runtime_contract.md`, `references/coordinator_summary_contract.md`
**MANDATORY READ:** Load `references/researchgraph_mcp_usage.md` when Stories cite H/G/run IDs or project researchgraph evidence can change priority confidence.

Runtime family: `planning-worker-runtime`

Identifier:
- `epic-{epicId}`

Phases:
1. `PHASE_0_CONFIG`
2. `PHASE_1_DISCOVERY`
3. `PHASE_2_LOAD_STORY_METADATA`
4. `PHASE_3_ANALYZE_STORIES`
5. `PHASE_4_GENERATE_PRIORITIZATION`
6. `PHASE_5_WRITE_SUMMARY`
7. `PHASE_6_SELF_CHECK`

Summary contract:
- `summary_kind=story-prioritization-worker`
- payload includes `epic_id`, `depth`, `stories_analyzed`, `priority_distribution`, `top_story_ids`, `prioritization_path`, `warnings`
- managed mode writes to caller-provided `summaryArtifactPath`
- default managed artifact path pattern: `.hex-skills/runtime-artifacts/runs/{parent_run_id}/story-prioritization-worker/ln-230--{identifier}.json`

**Table columns (from user requirements):**

| Priority | Customer Problem | Feature | Solution | Rationale | Impact | Market | Sources | Competition |
|----------|------------------|---------|----------|-----------|--------|--------|---------|-------------|
| P0 | User pain point | Story title | Technical approach | Why important | Business impact | $XB | [Link] | Blue 1-3 / Red 4-5 |

---

## Inputs

| Input | Required | Source | Description |
|-------|----------|--------|-------------|
| `epicId` | Yes | args, kanban, user | Epic to process |

**Resolution:** Epic Resolution Chain.
**Status filter:** Active (planned/started)

## Tools Config

**MANDATORY READ:** Load `references/environment_state_contract.md`, `references/storage_mode_detection.md`, `references/input_resolution_pattern.md`

Extract: `task_provider` = Task Management → Provider

## Research Tools

| Tool | Purpose | Example Query |
|------|---------|---------------|
| **WebSearch** | Market size, competitors | "[domain] market size {current_year}" |
| **mcp__Ref** | Industry reports | "[domain] market analysis report" |
| **hex-research** | Local hypothesis, goal, and benchmark evidence | `find_hypotheses`, `inspect_goal`, `find_runs` for explicit H/G/run context |
| **Task provider** | Load Stories | IF linear: list_issues / ELSE: Glob story.md |
| **Glob** | Check existing | "docs/market/[epic]/*" |

---

## Workflow

### Phase 1: Discovery (2 min)

**Objective:** Validate input and prepare context.

**Process:**

1. **Resolve epicId:** Run Epic Resolution Chain per guide.

2. **Load Epic details:**
   - **IF task_provider == "linear":** `get_project(query=epicId)`
   - **ELSE IF task_provider == "github":** `gh issue view {epicId} -R {REPO} --json number,title,body`
   - **ELSE:** `Read("docs/tasks/epics/epic-{N}-*/epic.md")`
   - Extract: Epic ID, title, description

3. **Auto-discover configuration:**
   - Read `docs/tasks/kanban_board.md` for Team ID
   - Slugify Epic title for output path

4. **Check existing prioritization:**
   ```
   Glob: docs/market/[epic-slug]/prioritization.md
   ```
   - If exists: Ask "Update existing or create new?"
   - If new: Continue

5. **Create output directory:**
   ```bash
   mkdir -p docs/market/[epic-slug]/
   ```

**Output:** Epic metadata, output path, existing check result

---

### Phase 2: Load Stories Metadata (3 min)

**Objective:** Build Story queue with metadata only and prepare rough scoring inputs for all Stories.

**Process:**

1. **Query Stories from Epic:**
   **IF task_provider == "linear":**
   ```
   list_issues(project=Epic.id, label="user-story")
   ```
   **ELSE IF task_provider == "github":**
   ```
   gh api /repos/{O}/{R}/issues/{epic_num}/sub_issues --jq '.[].number'
   → for each: gh issue view {num} -R {REPO} --json number,title,state,labels
   → filter: label "user-story"
   ```
   **ELSE (file mode):**
   ```
   Glob("docs/tasks/epics/epic-{N}-*/stories/*/story.md")
   ```

2. **Extract metadata only:**
   - Story ID, title, status
   - minimal Epic context if available
   - **DO NOT** load full descriptions yet

3. **Filter Stories:**
   - Exclude: Done, Cancelled, Archived
   - Include: Backlog, Todo, In Progress

4. **Build processing queue:**
   - Order by: existing priority (if any), then by ID
   - Count: N Stories to process

**Output:** Story queue (ID + title + minimal context), ~50-80 tokens/Story

---

### Phase 3: Two-Pass Story Analysis

**Objective:** Score all Stories cheaply first, then spend deep research only on candidates where it changes the decision.

**Critical:** Keep maximum context to one full Story at a time even during deep research.

If a researchgraph layout exists, run local graph checks only for Stories whose priority depends on hypothesis status, goal coverage, benchmark evidence, or implementation readiness. Local graph evidence can change RICE confidence and risk; it does not replace market-size or competitor research.

#### Pass A: Cheap Triage For All Stories

For each Story, load only enough detail to estimate:
- customer problem
- rough solution shape
- likely reach
- likely impact
- likely effort
- initial confidence tier

##### Step 3.1: Load Story Description

**IF task_provider == "linear":**
```
// configured tracker provider: getStory(id=storyId)
```

**ELSE IF task_provider == "github":**
```
gh issue view {storyId} -R {REPO} --json number,title,body,state,labels
```

**ELSE (file mode):**
```
Read("docs/tasks/epics/epic-{N}-*/stories/us{NNN}-*/story.md")
```

**Extract from Story:**
- **Feature:** Story title
- **Customer Problem:** From "So that [value]" + Context section
- **Solution:** From Technical Notes (implementation approach)
- **Rationale:** From AC + Success Criteria

##### Step 3.2: Build rough RICE estimate

Use Story + Epic context to assign:
- rough `Reach`
- rough `Impact`
- rough `Effort`
- initial `Confidence`

Mark one of:
- `full_research_required`
- `rough_estimate_ok`
- `borderline_needs_review`

**Send to Pass B only if:**
- candidate looks P0/P1 on rough score
- confidence is low
- Story is near a priority threshold
- Story has strategic or market-sensitive uncertainty

#### Pass B: Selective Deep Research

Only for Stories selected in Pass A, run full external research.

##### Step 3.3: Research Market Size

**WebSearch queries (based