ln-210-epic-coordinator

What this skill does

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

# Epic Coordinator

**Type:** L2 Domain Coordinator
**Category:** 2XX Planning

Universal Epic management coordinator that handles both creation and replanning through scope decomposition.

## Purpose

Coordinates Epic creation (CREATE) and replanning (REPLAN) from scope decomposition. Discovery and research stay read-only until preview is approved; execution remains inline inside ln-210.

## When to Use This Skill

This skill should be used when:
- Start new scope/initiative requiring decomposition into multiple logical domains (CREATE mode)
- Break down large architectural requirement into Epics
- Update existing Epics when scope/requirements change (REPLAN mode)
- Rebalance Epic scopes within an initiative
- Add new Epics to existing initiative structure
- First step in project planning (scope → Epics → Stories → Tasks)
- Define clear scope boundaries and success criteria for each domain

**Output:** 3-7 tracker Epics (logical domains/modules; transport per the configured provider)

## Runtime Contract

**MANDATORY READ:** Load `references/coordinator_runtime_contract.md`, `references/epic_planning_runtime_contract.md`, `references/epic_plan_summary_contract.md`
**MANDATORY READ:** Load `references/researchgraph_mcp_usage.md` when the project has `docs/hypotheses/`, `docs/goals/`, or benchmark run manifests that can change Epic boundaries.

Runtime family: `epic-planning-runtime`

Identifier:
- scope identifier

Phases:
1. `PHASE_0_CONFIG`
2. `PHASE_1_DISCOVERY`
3. `PHASE_2_RESEARCH`
4. `PHASE_3_PLAN`
5. `PHASE_4_MODE_DETECTION`
6. `PHASE_5_PREVIEW`
7. `PHASE_6_DELEGATE`
8. `PHASE_7_FINALIZE`
9. `PHASE_8_SELF_CHECK`

Decision handling:
- preview/confirmation is runtime `PAUSED + pending_decision`
- ln-210 writes final `epic-plan` summary for ln-200 when used as downstream coordinator

Coordinator artifact flow:
- execution remains inline inside ln-210
- `PHASE_7_FINALIZE` writes the coordinator summary through `node references/scripts/epic-planning-runtime/cli.mjs record-plan-summary`
- managed parent flow stores the artifact at `.hex-skills/runtime-artifacts/runs/{parent_run_id}/epic-plan/{identifier}.json`

## Worker Invocation (MANDATORY)

| Phase | Worker | Context |
|-------|--------|---------|
| 6 | None | CREATE/REPLAN execution is inline inside ln-210; no downstream Skill worker is delegated |

**Downstream contract:** ln-210 is itself a worker for `ln-200` and writes `epic-plan` machine-readable output after inline Epic create/replan execution completes.

## TodoWrite format (mandatory)

```text
- Phase 1: Discover scope and project context (pending)
- Phase 2: Research only what changes Epic boundaries (pending)
- Phase 3: Build ideal Epic plan (pending)
- Phase 4: Detect mode and validate Infra Epic need (pending)
- Phase 5: Preview and confirm plan (pending)
- Phase 6: Execute create/replan flow (pending)
- Phase 7: Finalize epic-plan summary (pending)
- Phase 8: Self-check (pending)
```

## Core Concepts

### Decompose-First Pattern

**Key principle:** ALWAYS analyze scope and build IDEAL Epic plan FIRST, THEN check existing Epics to determine mode:
- **No existing Epics** → CREATE MODE (generate and create all Epics)
- **Has existing Epics** → REPLAN MODE (compare, determine operations: KEEP/UPDATE/OBSOLETE/CREATE)

**Rationale:** Ensures consistent Epic decomposition based on current scope requirements, independent of existing Epic structure (which may be outdated or suboptimal).

### Epic 0 Reserved for Infrastructure

**MANDATORY READ:** Load `references/numbering_conventions.md` for Epic 0 rules, when to use it, and tracker numbering.

---

## Inputs

| Input | Required | Source | Description |
|-------|----------|--------|-------------|
| `scopeDoc` | Yes | args, project docs, user | Scope document for Epic decomposition |

**Resolution:** Epic Resolution Chain (adapted: scope doc discovery).
**Fallback:** IF no scope doc found → AskUserQuestion: "What should be decomposed into Epics?"

## Workflow

### Phase 0: 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

### Phase 1: Discovery

**Objective:** Gather the minimum context required to shape Epic boundaries before any preview or mutation.

**Step 0: Resolve scopeDoc** (per input_resolution_pattern.md, adapted for scope):
- IF args provided (scope description or doc path) → use args
- ELSE IF `docs/project/requirements.md` exists → use as scope source
- ELSE IF `docs/requirements.md` exists → use as scope source
- ELSE → AskUserQuestion: "What should be decomposed into Epics?"

**Step 1: Load Configuration**

Auto-discovers Team ID and Next Epic Number from `docs/tasks/kanban_board.md`:
- **Team ID:** Reads Tracker Configuration table → Fallback: Ask user directly
- **Next Epic Number:** Reads Next Epic Number field → Fallback: Ask user directly

**MANDATORY READ:** Load `CLAUDE.md` — sections "Configuration Auto-Discovery" and "Tracker Integration".

### Phase 2: Research

**Objective:** Research only what changes Epic boundaries, Infra Epic need, or batch preview quality.

**Step 1: Project Research**

**Objective:** Research project documentation AND frontend code to understand context BEFORE asking user questions.

**Process:**

0. **Researchgraph Preflight (if present):**
   - If `docs/hypotheses/`, `docs/goals/`, or `benchmark/runs/*/manifest.yaml` exists, run read-only `verify_index` first.
   - Use `inspect_goal`, `trace_goal_tree`, `find_hypotheses`, or `audit_goal_alignment` only when goals/hypotheses can change Epic boundaries, validation scope, or promotion/generalization work.
   - Treat `STALE` graph debt as planning context, not as an Epic blocker by itself.

1. **Document Scan:**
   - Use `Glob` to find: `docs/requirements.md`, `docs/architecture.md`, `docs/tech_stack.md`
   - Use `Read` to load found documents

2. **Frontend Code Scan (if applicable):**
   - Use `Glob` to find: `**/*.html`, `src/**/*.html`, `public/**/*.html`, `templates/**/*.html`
   - Use `Read` to load HTML files
   - Extract functional domains from:
     - **Navigation menus:** `<nav>`, `<a href>` links reveal feature areas
     - **Forms:** Input fields reveal data models (user registration, login, checkout)
     - **Page titles:** `<h1>`, `<title>` tags reveal feature names
     - **Route patterns:** URL structures reveal domain boundaries

   **Example HTML extraction:**
   ```html
   <nav>
     <a href="/products">Products</a>
     <a href="/cart">Shopping Cart</a>
     <a href="/checkout">Checkout</a>
   </nav>
   <!-- Reveals domains: Product Catalog, Shopping Cart, Payment -->
   ```

3. **Extract key information from docs + HTML:**
   - **Business objectives:** What is the project trying to achieve? (from requirements.md)
   - **User personas:** Who will use the system? (from requirements.md)
   - **Major functional domains:** What are the main modules/areas? (from requirements.md, architecture.md, HTML navigation)
   - **Technical stack:** What technologies mentioned? (from tech_stack.md, architecture.md, HTML meta/script tags)
   - **Infrastructure requirements:** Any mention of logging, monitoring, deployment, CI/CD, security, performance optimization?

4. **Combine findings:**
   - Merge domains from docs + HTML (deduplicate, consolidate similar)
   - Example: "User Auth" (from docs) + "Login" (from HTML) → "User Management"

**Fallback:** If docs AND HTML missing → Skip to scope questioning; do not invent research-heavy detail

**Step 2: Infrastructure Epic Decision**

**Objective:** Determine if Infrastructure Epic (Epic 0) should be proposed.

**Criteria for Infrastructure Epic:**

✅ **PROPOSE Infrastructure Epic (Epic 0)** if ANY of:
1. **New project** (no `docs/infrastructure.md` found, no Epic "Infrastructure" in k