# Epics > Jira-driven Epic-writing workflow. Reads a Value Increment and existing Epics from exported markdown, optionally scans code repos, drafts child Epic definitions, and gates on dt-style-checker and Opus epic-reviewer. Activated when the user prompt starts with "epics:". - Skill: `ihudak/epics` (Agent Skill) - Install (CLI): `npx skillmds@latest add ihudak/epics` - Raw SKILL.md: https://api.skillmd.com/api/skills/ihudak/epics/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ihudak (https://skillmd.com/u/ihudak) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ihudak/epics --- Draft child Epics for the Jira Value Increment: the argument (text following the `epics:` trigger) `epics:` is the **Jira-driven Epic-writing** workflow. Given a Value Increment key, it reads the VI plus its existing Epics from pre-exported markdown in the user's Obsidian vault, optionally scans code repos to identify reusable capabilities and gaps, drafts child Epic definitions as markdown files under the resolved output directory, and gates the result on an Opus review. Key distinction from `document:` (Jira mode): the VI being Epic-ized is **not yet implemented** — there are no PRs to diff. Code scanning (when enabled) is a plain filesystem search to understand what exists and what needs to be built. `epics:` **never branches** and **never commits the Epic drafts** (still true — the run's git **writes** are confined to `$SPECS_PATH`, per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md`; the run does make read-only git calls elsewhere — Phase 4's `git remote get-url origin` per candidate clone and Phase 8's `git diff --stat` from `project_root` — but none of them writes), and writes only to the resolved output directory — `jira-drafts//` under `$VAULT_PATH`, or a derived `epic-drafts//` dir beside the imported hierarchy when `$VAULT_PATH` is unset. Git hygiene of the write target is the user's responsibility — they may or may not have it under version control. The run commits only inside `$SPECS_PATH`, and only its bounded session-artifact paths (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` §2.1) — via the `specs-preflight` flush at run start (§3.4) and the terminal `commit-artifacts` step (§4); never the drafts, never the write target. It still creates no branch (still true — `specs-preflight` switches `$SPECS_PATH` only between branches that already exist, and only plugin-created ones (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` §2.2); it creates none). --- ## Phase 0 — Load 1. **Resolve the Jira input via the shared front-end.** Execute `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/jira-input-resolution.md` against the argument (text following the `epics:` trigger). `epics:` is **jira-driven only**: expect `mode: jira-driven` with `jira_key` (the input Value Increment key), `jira_export_root` (the VI export dir — `$VAULT_PATH/jira-products/` for a JiraID, or the passed directory), and `source`. The front-end owns the `$VAULT_PATH` / `jira-products` validation and Fallbacks A/B. Carry `jira_key`, `jira_export_root`, and `focus_key` forward. Downstream, `` and `` both denote this `jira_key`. If the front-end returns `mode: direct` (no Jira input), stop with `EPICS_NEEDS_JIRA: epics: needs a Jira key or an imported-Jira directory.` — `epics:` has no direct-prompt behavior. `epics:` is **cwd-agnostic**: it writes Epic drafts to an absolute output directory (resolved in Phase 1), so it does **not** require cwd to be inside the vault. **Specs-repo preflight.** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` and execute its `specs-preflight` entry point (§3) inline: flush any leftover session artifacts from an earlier run, retry an artifact commit that failed to push, and settle the branch. Prompt-free and silent when the specs repo is clean and on its default branch. If a guard fires, emit its §5 notice; if it returns `specs_git: blocked` (§3.3 G0), carry that flag for the whole run — the terminal `commit-artifacts` step skips on it. --- ## Phase 1 — Clarification **Rule: Ask, don't guess. This rule is absolute.** Group questions where possible; use `choices` arrays; the last choice in every array MUST be `"Other… (describe)"`. Ask about: - **Output directory.** One `.md` file per Epic, filename `.md` (drafted Epics have no Jira ID yet, so they are slug-named files inside the VI-keyed folder). The default depends on `$VAULT_PATH`: - **`$VAULT_PATH` set** → `$VAULT_PATH/jira-drafts//`. This lives **outside** `jira-products/` by design — `jira-products/` is re-created on every Jira import, so drafts written there would be lost; `jira-drafts/` is a sibling reserved for PM/PO work-in-progress that survives re-imports. - **`$VAULT_PATH` unset** (directory input) → `/epic-drafts//`. **Path-safety guard:** warn and offer another path if this dir would fall *inside* `jira_export_root` (wiped and regenerated on every import). A pre-existing dir that already holds drafts is normal — **not** a warning. The directory is auto-created if missing. Record `output_dir`, and record `project_root` = `$VAULT_PATH` when set, else `output_dir`. Ask: ``` choices: ["Use (Recommended)", "Use a different path (you'll be prompted)", "Cancel", "Other… (describe)"] ``` - **Code examination on/off** (default ON). If ON, ask which repos under `$REPOS_PATH` to scan: ``` choices: ["Scan repos referenced by sibling/parent Epics under this VI (Recommended — auto-derived)", "Let me list the repos manually (you'll be prompted)", "Turn code scan off — produce Epic drafts from Jira content alone", "Other… (describe)"] ``` When "auto-derived" is chosen, inspect the sibling/parent Epics' `## Pull Requests` sections (if any) for repo references; if none, fall back to asking the user to list repos. - **Repo refresh policy** (only if code scan is ON): ``` choices: ["fetch + pull default branch (Recommended)", "fetch only", "no refresh", "Other… (describe)"] ``` The `fetch + pull default branch` default matches `code-scanner`'s default (`refresh.switch_to_default_branch: true, refresh.pull: true`) — capability scans target present-day code and want the default-branch tip. This is deliberately different from `document:` (Jira mode), which keeps `pull: false` because historical merged commits must not move. - **Repos search base (`$REPOS_PATH`)** (only if code scan is ON). Read `${REPOS_PATH:-/workspace}` (the container mounts every repo under `/workspace`). `$REPOS_PATH` may be a single directory or a colon-separated list. Ask: ``` choices: ["Use $REPOS_PATH (default /workspace) (Recommended)", "Use a different path (you'll be prompted)", "Cancel", "Other… (describe)"] ``` If "different path", take free-text input (single dir or colon-separated list) and validate that at least one directory exists under it. Record the resolved value as `$REPOS_PATH`. Individual clones are located in Phase 4 by matching their `git remote` against each repo slug — not by assuming a `/` directory name. Also display (for user context): - Resolved cwd absolute path - Resolved output directory - Resolved `$REPOS_PATH` (or "N/A — code scan off") - Resolved `jira_export_root` and `jira_key` (plus `$VAULT_PATH` when set) No branching context is shown — this command never branches (still true — `specs-preflight` only switches `$SPECS_PATH` between branches that already exist, and only ones the plugin created, per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` §2.2; it creates none). --- ## Phase 1.5 — Classify Load and follow the model-routing policy at `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/model-routing.md`, then classify the task as exactly one of: `SIMPLE`, `MODERATE`, `SIGNIFICANT`, or `HIGH-RISK`. Epic writing is typically **MODERATE** (bounded scope, single VI, vault-internal output). State the classification and a one-sentence reason. MODERATE → no separate Opus planner; the `epic-reviewer` gate (Opus, dispatch-pinned to this chain) is mandatory. Resolve the per-step routing per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/model-routing.md` §9: ```yaml model_routing: classification: MODERATE # typical; SIGNIFICANT possible reason: current_model: detection_model: <§2.1 detection chain: claude-sonnet-4.6, fallback claude-sonnet-4.5/gpt-5.4> # jira-reader, code-scanner, dt-style-checker, doc-fixer, epic-writer (MODERATE) review_model: <§2 Opus chain> # epic-reviewer (dispatch-pinned to this chain; recorded, no override) implementation_model: <= detection_model> # the epic-writer subagent (Phase 6); planning_model if SIGNIFICANT/HIGH-RISK opus_available: notes: ``` Each subagent dispatch below cites its chain (§9 role→chain map). **No relaunch advisory** for MODERATE — the writer runs on its detection pin and the gates run on `current_model`, which §3.1 allows (if a run is classified SIGNIFICANT/HIGH-RISK, the §9.1 advisory applies and `epic-writer` escalates to the §2 chain). If no Opus is available, `epic-reviewer` falls to the Sonnet floor — record the degradation in `notes` and the Phase 9 report. --- ## Phase 2 — Plan + approval **Documentation grounding (optional, independent of code scan).** Before presenting the plan below, run `resolve-docs-grounding epics` per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/docs-grounding.md` — this is the run's only consent-bearing step (an index build or a capped refresh), so it must resolve here, before Phase 3's `jira-reader`, Phase 4's repo resolution, and Phase 5's parallel code scan do any of the run's real work. This runs ahead of Phase 2.5/2.6's `require-on-main`/`ard-resolution.md` gates — a deliberate exception to `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §5 rule 2's ordering, kept here rather than moved because `resolve-docs-grounding`'s only expensive step is itself behind its own consent prompt (`docs-grounding.md` step 3.5), and an index build it produces is a durable, run-independent artifact, not per-run work a later stop would waste. Present a concise plan: - Resolved `jira_key` and the `jira_export_root` path - Existing Epics identified under this VI (will NOT be duplicated) - Repos to scan (or "code scan off") - Docs grounding: the `docs grounding:` line that `resolve-docs-grounding` returned, verbatim — including its `retrieval:` value and any index-build, staleness, or shadowing clause (off switch: --no-docs) - Output directory with one file per new Epic; propose a name stub per Epic if the themes already suggest them - Parallelism plan (up to 4 `code-scanner` instances per batch, single task message per batch) - Proposed Epic sizing/sequencing — prefer fewer, larger Epics where the VI direction is validated; split only at a genuine risk / feedback-loop boundary; order so that no Epic depends on a later one - **Wide-refactor exception** — a blast-radius-wide *mechanical* change (rename/retype a shared symbol, column, or type) that genuinely cannot be tracer-bulleted into independent vertical slices is sequenced **expand → migrate-in-batches → contract**: one Epic adds the new form alongside the old, one-or-more Epics migrate call sites in batches, and a final Epic removes the old form (blocked by every migrate-batch). Prefer this over forcing the change into an awkward vertical slice Ask: ``` "Epic drafting plan ready. What would you like to do?" choices: ["Approve & continue (Recommended)", "Revise plan", "Cancel"] ``` - **Approve** → proceed to Phase 3 - **Revise** → ask what to change, update, re-show, re-ask - **Cancel** → stop and summarise what was planned --- ## Phase 2.5 — Resolve applicable ARD (optional) Resolve any VI-level ARD for this VI by citing `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/ard-resolution.md` with `vi = jira_key`, **`epic: null`** (Epics do not exist yet — VI-level ARD only), and `$SPECS_PATH`. - On `status: none` (including `$SPECS_PATH` unset/unresolvable) → **skip and proceed exactly as before.** No prompt, no extra output. - On `status: unmerged` → **stop**, naming the returned `branch` and any `pr` — an ARD that exists but has not landed on `` is a weaker architectural basis than the one about to arrive, and Epics drafted against it would need re-doing once it does. - On `status: found` → carry `invariants` + `guidance_summary` forward: pass them to `epic-writer` (Phase 6 handoff, as `applicable_ard`) so drafts stay consistent with the `AD#N`, and to `epic-reviewer` (Phase 7, as `applicable_ard`) which then activates its ARD-conformance dimension. A necessary deviation is recorded by the writer in the Epic draft (`- ARD deviation: … flag: architect`) and surfaced in the Phase 9 report — never edit the ARD. --- ## Phase 2.6 — VI-level spec enrichment (optional) If a VI-level specification exists, fold its requirements into the coverage inventory. **Additive, zero-cost when absent** — the common case, since `specify:` usually runs per-Epic *after* `epics:`. 1. **Resolve the VI dir:** `$SPECS_PATH/specifications/-/`, matched by key-number, tolerating a stray `-`/`_` and a human-adjusted slug (the same rule `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/ard-resolution.md` step 1 uses). If `$SPECS_PATH` is unset/unresolvable, or no VI dir matches → **skip** (set `vi_spec_present: false`). 2. **Detect:** execute `require-on-main` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §3) against `/specification.md`, mapping its §3.7 return value by `stopped` first, never by `on_main` alone. On any stopping state, stop per §4.4, naming `$SPECS_PATH` explicitly — a spec that exists but has not yet landed on `` is a weaker grounding basis than the one about to arrive, and Epics drafted against it would need re-doing. Otherwise (`stopped: false`): on `pass`/`pass_amending`, proceed to step 3 (`pass_amending` prints §3.3's row-B message). On `unmanaged`, behave exactly as before this feature — **skip** (set `vi_spec_present: false`). On `absent`, **skip** (set `vi_spec_present: false`); the run proceeds byte-identically to today — this is the common case, and VI-level `specify:` remains optional. 3. **Parse** `/specification.md` directly (Read it — one file, a simple heading scan): extract its user stories `[Uxx]` and their nested acceptance criteria `[ACxx]` into `vi_spec_requirements[]`. **Skip `[TCxx]` test cases** (per-AC, non-unique, below Epic granularity) and the prose sections (Problem/Scope). Because `[ACxx]` numbering restarts per story, qualify each `spec-criterion` id with its parent story (`/`) so every `Req` id in `_coverage.md` is unique; `spec-story` `[Uxx]` ids are document-unique and used as-is: ```yaml vi_spec_requirements: - id: / (criterion)> # spec-story id is document-unique; qualify criterion ids with the parent story type: spec-story | spec-criterion text: ``` Set `vi_spec_present: true` and record the resolved `specification.md` path for the Phase 9 report. --- ## Phase 3 — Read Jira hierarchy Invoke `jira-reader` with `depth: vi-plus-epics`. This depth is specifically designed for Epic writing: richer than `vi-only` so themes extracted for `code-scanner` aren't starved of context, but lighter than `full` so the agent doesn't read dozens of already-closed child Stories. → task(agent_type: "dev-workflows:jira-reader", model: ``): > "Return the structured handoff for this brief: > > jira_export_root: [resolved jira_export_root] > jira_key: [resolved jira_key] > depth: vi-plus-epics" Wait for the handoff. If `status: NOT_FOUND` or `status: EMPTY`, surface the `Jira key dir not found` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md` (`["Re-enter key", "Cancel"]`). On `OK`, carry the handoff `requirements[]` and `requirements_source` forward — they are the coverage ground truth for Phases 6–7. When Phase 2.6 set `vi_spec_present: true`, **append** its `vi_spec_requirements[]` to this `requirements[]` — the VI's own rows are unchanged; the appended rows carry `type: spec-story` / `spec-criterion`, which separates them from the VI's `story`/`criterion` rows. The merged list flows unchanged into the Phase 6 handoff and the Phase 7 reviewer brief. When `vi_spec_present: false`, `requirements[]` is exactly what `jira-reader` returned. On `OK`, identify the Epics already linked to the VI (filter `linked_items` to `type == Epic`) — the new Epic drafts MUST NOT duplicate their scope (enforced later by `epic-reviewer`). **Refinement target (`focus_key`).** `epics:` always reads and analyses the whole VI (the partition and non-duplication logic are inherently VI-holistic). When `focus_key` is set (explicit ` `), validate it is among the linked Epics; if it is not, surface `EPICS_FOCUS_NOT_FOUND: is not a linked Epic of .` and offer `choices: ["Proceed VI-level (draft the full partition)", "Re-enter the Epic key", "Cancel"]`. When present, treat `focus_key` as the **single refinement target**: Phase 6 re-drafts only that Epic's definition, and Phase 7 reviews only that file. The non-duplication set (`existing_epics`) is the *other* linked Epics — exclude the focus Epic so Phase 6 re-emits it rather than skipping it as a duplicate. When `focus_key` is null, behaviour is unchanged (draft the full partition of new Epics). When `focus_key` is set, `mode = refine` and `refinement_targets = [the focus Epic]` — Phase 6 iterates on its current imported content (see `epic-writer` refinement mode) rather than regenerating from the VI alone. **Refinement candidates.** From the same `linked_items` (`type == Epic`), read the additive per-Epic fields `refinement_candidate`, `team`, and `scope_hint` (emitted by `jira-reader` at `vi-plus-epics`). Collect `refinement_candidates` = every linked Epic with `refinement_candidate: true`. These are empty/almost-empty team-Epic shells the PE pre-created to encode team boundaries — refinement *targets to fill in*, not non-duplication constraints. This set drives the Phase 3.5 gate. --- ## Phase 3.5 — Refinement-mode gate (conditional) Runs only when `focus_key` is set OR `refinement_candidates` is non-empty. Otherwise skip silently — `mode = generate`, behaviour byte-identical to the legacy net-new flow. **Focus key set** → `mode = refine`, `refinement_targets = [focus Epic]`; skip the mode question (the PE named the target explicitly). **No focus key, `refinement_candidates` non-empty** → present the detected set as a CONFIRMABLE list (detection only *proposes*; the PE is the authority) and ask the mode: ``` Detected N empty/almost-empty team-Epic shells linked to : - · · ... choices: ["Refine these N (partition the VI across them) (Recommended)", "Generate net-new Epics (ignore the shells)", "Both — refine the shells and draft net-new for leftover scope", "Let me adjust which shells to refine (you'll be prompted)", "Other… (describe)"] ``` Record `mode` (`refine` | `generate` | `both`) and the confirmed `refinement_targets` (empty for `generate`). A target whose `team` is empty carries a `[NEEDS CLARIFICATION — team]` note into the writer handoff. **Adaptive code-scan default (refine / both only).** Re-surface the code-examination choice now that the target count is known — the Phase 1 answer was given before detection. Default **ON when `len(refinement_targets) >= 2`** (a real cross-team boundary to draw), **OFF when == 1**: ``` choices: [" (Recommended)", "", "Keep my Phase 1 choice", "Other… (describe)"] ``` with a one-line rationale ("2+ team-Epics → code context helps draw the boundary" / "single Epic → no cross-team boundary; scan off is faster"). This runs ONLY in the refine branch, so the generate / no-candidate path never sees it (no-regression). --- ## Phase 3.6 — Documentation grounding dispatch **Documentation grounding dispatch (optional, independent of code scan).** `docs_grounding` was already resolved in Phase 2 — consume that cached result here; never re-run `resolve-docs-grounding`. When `docs_grounding: ON`, `dispatch-docs-grounder` with `feature_summary` = the VI goal + Epic-set intent, `jira_key` = the VI key, `themes` = the `jira-reader` themes. Carry the digest into Phase 6 with **writer-attach** consumption. When OFF, skip silently. This phase sits **before** the conditional repo-resolution and code-scanning phases deliberately. It needs only Phase 3's output — the VI goal and the `jira-reader` themes — and nothing from the code scan, and Phase 4 and Phase 5 both skip to Phase 6 when code scan is OFF. Dispatching from inside either of them would discard the digest on exactly the runs that turned code scanning off, after Phase 2 had already asked the user to consent to building an index for it. --- ## Phase 4 — Resolve repos (conditional) If code scan is OFF, skip to Phase 6. If code scan is ON: 1. Derive the repo list: - **Auto-derived** (Phase 1 default) — walk the `jira-reader` `linked_items` filtered to `type == Epic`; for each Epic `.md` file (already read during Phase 3), collect repo names from its `## Pull Requests` section URLs. Dedupe. If the auto-derived list is empty, fall back to asking the user. - **Manual list** — prompt for a free-text list of repo short names (one per line or space-separated). Resolve each against the `$REPOS_PATH` slug→clone map built in step 2 below. 2. Build a slug→clone map. For each top-level directory under each entry of `$REPOS_PATH`, run `timeout 5 git -C remote get-url origin 2>/dev/null`, strip a trailing `.git`, and take the URL's last path segment as that clone's slug. Skip directories with no `.git` or whose `git remote` call fails/times out. Resolve each in-scope repo slug against the map: one match → use it; multiple matches → auto-prefer basename ending `-repo`, then `_repo`/`_fast`, then alphabetically last (show candidates at plan approval); zero matches → escalate per the `Repo unresolved (zero matches) — epics:` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md`: ``` choices: ["Skip and continue without this repo's scan", "I'll clone it — wait", "Cancel", "Specify a different absolute path for this repo", "Other… (describe)"] ``` 3. If the final resolved repo list is empty (every repo was skipped or missing), escalate per the `No repos derivable — epics:` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md`: ``` choices: ["List repos to scan manually", "Proceed without code scan", "Cancel", "Other… (describe)"] ``` --- ## Phase 5 — Parallel code scanning (conditional) If code scan is OFF, skip to Phase 6. Spawn `code-scanner` instances in **batches of up to 4 concurrent agents** per task message. Wait for each batch before spawning the next. For each repo in the batch: → task(agent_type: "dev-workflows:code-scanner", model: ``): > "Scan this repo for the brief: > > repo_path: > repo_url_slug: > capability_themes: > [paste the themes array from jira-reader, plus any VI-goal-derived themes] > context: | > [3–5 sentences: VI goal, what the Epic-set is meant to achieve] > search_hints: > symbols: [class/function names inferred from VI/Epic descriptions, or []] > paths: [directory globs inferred from themes, or []] > keywords: [grep keywords extracted from themes] > refresh: > switch_to_default_branch: [true if Phase 1 chose 'fetch + pull default branch' (default) or 'fetch only'; false if 'no refresh'] > pull: [true if 'fetch + pull default branch'; false otherwise]" Handle per-repo status after the batch returns: - `OK` / `PARTIAL` / `EMPTY` — store the output, continue. - `REPO_MISSING` — should not happen at this stage (Phase 4 already checked). If it does, escalate per the `Repo missing (after resolution)` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md`. - `DIRTY_TREE` — escalate: ``` choices: ["Stash changes and retry this repo", "Skip this repo", "Cancel"] ``` - `REFRESH_BLOCKED` — escalate: ``` choices: ["Continue with current local state", "Skip this repo", "Cancel"] ``` - `prep.read_only: true` — not a failure. The scan ran at `prep.scanned_ref`. Escalate per the `Read-only mount — ref stale or diverged` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md` **only** when `prep.ref_committed_at` is more than 14 days old or `prep.head_divergence.ahead > 0`; otherwise proceed silently and cite evidence at `prep.scanned_ref`. --- --- ## Phase 6 — Write Epics The drafting is delegated to the **`epic-writer`** subagent (pinned to the §2.1 detection chain for MODERATE; §2 Opus only if the run is SIGNIFICANT/HIGH-RISK — see `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/model-routing.md` §9.2). The orchestrator prepares a handoff and dispatches; it does not write Epics itself, and **nothing commits in this phase** (still true — `epics:` never branches, and the Epic drafts it writes are never committed; git hygiene of the write target is the user's responsibility. The run commits only inside `$SPECS_PATH`, and only its bounded session-artifact paths, per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` §2.1). 1. **Write the handoff file.** Create a temp file (`mktemp` — never the vault, never a repo) containing the `epic-writer` input contract: `jira_reader_handoff`, `code_scanner_outputs` (empty if no scan), `scope` (Phase 2 in/out of scope), `existing_epics` (non-duplication), `output_dir` (resolved Phase 1 dir), `vi_goal`, `jira_key`, `requirements` + `requirements_source` (from Phase 3), `applicable_ard` (the Phase 2.5 invariants + guidance_summary, or omit when status was none), `existing_epic_themes` (themes of the already-linked Epics), `mode` (`generate` | `refine` | `both` — from Phase 3.5; `generate` when 3.5 skipped), and `refinement_targets` (list of `{key, team, scope_hint, current_body_path}`, where `current_body_path = //.md`; empty in `generate` mode), and `docs_grounding` (the Phase 3.6 digest, or omit when OFF/EMPTY). Record its absolute path. When `focus_key` is set (the Phase 3 refinement target), set `scope` in-scope to just the focus Epic and `existing_epics` to the *other* linked Epics, so `epic-writer` re-drafts the single focus Epic's definition file; `output_dir` is unchanged. 2. **Dispatch the writer:** → task(agent_type: "dev-workflows:epic-writer", model: ``): > "Write the child Epic definitions for this brief. > > handoff_file: [absolute path of the temp handoff file from step 1]" 3. **Handle the return.** `status: DONE` → record `files_written` for Phase 6.1 onward. `status: BLOCKED` → surface the named gap: ``` choices: ["Provide the missing input (you'll be prompted)", "Cancel"] ``` On a provided value, rewrite the handoff and re-dispatch once. Nothing is committed here (still true — this step writes only Epic drafts into the vault / output directory, which `commit-artifacts` never stages; git management there is the user's responsibility). Also record `coverage_file` (the `_coverage.md` path) and `clarifications_needed[]` for Phases 6.1 and 7. --- ## Phase 6.1 — Resolve clarifications If the writer returned a non-empty `clarifications_needed[]`, resolve it BEFORE the style check and review (so no review cycle is spent on known unknowns). Present ONE batched prompt listing every marker grouped by Epic; for each: ``` choices: ["Use the writer's suggested answer", "I'll answer (you'll be prompted)", "Leave unresolved", "Other… (describe)"] ``` Fold each resolved answer into the affected Epic draft (Edit the file inline, or re-dispatch `epic-writer` once with the resolutions). Markers the user chooses to **leave unresolved** stay visible in the draft and become `epic-reviewer` BLOCKERs in Phase 7. If `clarifications_needed[]` is empty, this phase is a **silent no-op** (byte-identical to a run without it). **Leftover disposition (refine / both only).** After the writer returns, read `_coverage.md`; every `❌ gap` row is a VI requirement no team-Epic covers. In ONE batched prompt, ask per gap: ``` choices: ["Assign to team-Epic (re-drafts that Epic to include it)", "Propose as a new (net-new, slug-named) Epic", "Defer (leave as an uncovered row)", "Other… (describe)"] ``` Fold the results back: *assign* → re-dispatch `epic-writer` once (or Edit inline) to add the requirement to the named target's `## Covers` + scope; *new Epic* → add a slug-named net-new draft; *defer* → the row stays `❌ gap` in `_coverage.md` and is listed in the Phase 9 report. Reuses the same batched-gate pattern as the clarification resolution above; no gaps → silent no-op. --- ## Phase 6.2 — Dynatrace style check Invoke `dt-style-checker` on the files written in Phase 6. Unlike `document:` (Jira mode), this does NOT use `docs-style-checker` (no repo linter for vault content). Instead, the Dynatrace corporate style guide checker validates terminology, trademarks, voice/tone, and inclusive language. → task(agent_type: "dt-style-guide:dt-style-checker", model: ``): > "Run the style check for this brief: > > files: [absolute paths of every Epic file written in Phase 6] > doc_type: epic > emphasis: terminology and customer-facing captions, labels, messages, and text" Act on the return: - **`status: OK`** — zero violations. Proceed to Phase 7. - **`status: VIOLATIONS_FOUND`** — invoke `doc-fixer` with the violations treated as per their severity. After `doc-fixer` completes, re-run `dt-style-checker` once: → task(agent_type: "dev-workflows:doc-fixer", model: ``): > "Fix the style violations for this brief: > > Task description: [Epic drafting for ] > Reviewer or style-checker output: [paste full dt-style-checker output] > Project root: [resolved project_root] > Severities to fix: MAJOR only" If violations remain after the re-run, proceed to Phase 7 — the remaining findings (mostly MINOR/NIT for epics) are informational and will appear in the Phase 9 report. - **`status: ERROR`** — surface the error reason. Proceed to Phase 7 regardless (style check is not a gate for Epics, but a quality enhancement). If `dt-style-checker` is unavailable (agent file not found), proceed directly to Phase 7. The style check is optional but recommended. --- ## Phase 6.3 — Structural pre-lint Before the review gate, run the deterministic checks in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/pre-lint.md` against each drafted Epic file: the **Universal checks**, the **Jira-key collision** check (run on the whole Epic file — the template has no frontmatter), and the **Epic** block (required headings incl. `## Independent Test`; Given/When/Then acceptance criteria; `[NEEDS CLARIFICATION]` ≤ 3 per Epic; `_coverage.md` present). Surface every finding; inline-fix the mechanical ones (delete a stray placeholder token); leave content gaps for the author. **Advisory** — never blocks; proceed to Phase 7 once findings are surfaced. `epic-reviewer` remains the gate. ## Phase 7 — Epic review gate Invoke `epic-reviewer` (Opus). This reviewer is Epic-specific — scope clarity, acceptance-criteria testability, non-duplication of existing Epics. `docs-style-checker` is NOT used here (no repo linter for vault content); Dynatrace corporate style is handled by the Phase 6.2 `dt-style-checker` step above. → task(agent_type: "dev-workflows:epic-reviewer"): > "Review the Epic drafts for this brief: > > Task description: [one-paragraph: VI key, VI goal, number of Epics drafted] > Written Epic file paths: [absolute paths of every Epic file written in Phase 6] > jira-reader handoff: [paste full YAML from Phase 3] > code-scanner output: [paste array of per-repo scanner outputs from Phase 5, or 'N/A — code scan off'] > requirements: [paste the requirements[] array from Phase 3] > _coverage.md path: [absolute path of the coverage file from Phase 6] > applicable_ard: [the Phase 2.5 invariants, or omit if status was none]" When `mode` is `refine`/`both`, include `refinement_targets` in the `epic-reviewer` brief so its conditional refinement dimensions (completeness, partition integrity, cross-team dependency sanity, team preserved) activate; omit it in `generate` mode so those dimensions report N/A. Act on the verdict (same shape as `document:` Jira mode Phase 7): **Triage sub-step** (before any fixer dispatch): follow `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/finding-triage.md`. For each finding, verify its claimed consequence at the location it names; keep or dismiss; record every dismissal with a reason that disposes of that finding's own claim. Hand the fixer **survivors only**, and carry the dismissal list into this run's report. - **BLOCK** — invoke `doc-fixer` with `Severities to fix: BLOCKER and MAJOR`. Write the `doc-fixer` Fix Report to a temp file (`mktemp -t dw-epics-claims-XXXX.md`, never inside a repo tree or the vault), record its path as `claims_file`, then **check `doc-fixer`'s `Stop condition flag` before re-invoking anything**. If it is `NEEDS HUMAN`, the fixer deferred at least one BLOCKER as needing a human decision: do NOT re-invoke `epic-reviewer` — a re-review can only re-find the BLOCKER the fixer has just reported it could not resolve — and instead surface each deferred BLOCKER with the reason the fixer gave, then escalate it individually per the `Review verdict BLOCK (unresolved after one fix cycle) — epics:` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md`, which names this entry point alongside the second-BLOCK one. Only when the flag is `CLEAR` do you re-invoke `epic-reviewer` once **passing `claims_file`** — so the re-review falsifies the fixer's account rather than assuming it. If still BLOCK, escalate per the `Review verdict BLOCK (unresolved after one fix cycle) — epics:` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md` for each unresolved BLOCKER individually: ``` choices: ["Provide manual fix notes (you'll be prompted)", "Defer to a follow-up issue (record in Phase 9 report)", "Override and accept the finding", "Cancel the whole run", "Other… (describe)"] ``` For `epics:`, "Defer" means the finding goes into an Epic-refinement note in the draft itself (appended as a `## Refinement notes` section) in addition to the Phase 9 report. - **PASS WITH RECOMMENDATIONS** — invoke `doc-fixer` for MAJOR findings only: → task(agent_type: "dev-workflows:doc-fixer", model: ``): > "Fix the review findings for this brief: > > Task description: [Epic drafting for ] > Reviewer or style-checker output: [paste the triaged survivor list from the triage sub-step above — the surviving `epic-reviewer` findings only, never the dismissed ones] > Project root: [resolved project_root] > Severities to fix: BLOCKER and MAJOR" MINOR / NIT findings are deferred to the Phase 9 report. - **PASS** — proceed to Phase 8. Cap: one fix cycle + one re-review maximum. --- ## Phase 8 — Post-write maintenance First gather the change context: a. `project_root` (the vault when `$VAULT_PATH` is set, else the resolved output directory) is the "project root" for this run. Run `git diff --stat` from `project_root` if it is a git repo; otherwise list the written files manually. This command never commits anything under `project_root` — just report what changed (the terminal `commit-artifacts` step commits ONLY `$SPECS_PATH`'s bounded artifact paths, per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` §2.1). b. Compose a **change summary block**: ``` Implementation: [one-sentence description: how many Epics drafted for , resolved output directory] Change type: docs Classification: MODERATE Files changed: Notable additions/removals: [new Epics by slug — one line each] (In `refine`/`both` mode, refined Epics are identified by key ``, not slug.) Epic-review verdict: [PASS | PASS WITH RECOMMENDATIONS | BLOCK] ``` Then spawn all four maintenance agents in a **single task message**. They are independent and run concurrently. **Agent 1 — Documentation** (general-purpose): > "Post-write documentation review. Change summary: > [paste change summary block] > > The project root is an Obsidian vault when `$VAULT_PATH` is set, else the resolved output directory; look only for internal documentation files that reference Epic drafts (e.g., a `jira-drafts/README.md` or an index page enumerating active drafts). > Determine if any such file needs updating — e.g., a new entry in a drafts index. > Skip if: no such file exists or drafts aren't indexed centrally. > If an update is warranted: apply minimal edits. > Return: file updated and what changed, OR 'no update required (reason)'." **Agent 2 — Knowledge base** (general-purpose): > "Post-write knowledge review. Change summary: > [paste change summary block] > > Check ~/.copilot/memory/ (global) and .copilot/memory/ (project-level, preferred for vault-specific knowledge) for existing knowledge files. > Determine if a new knowledge entry is warranted — look for: reusable insights about this VI-family's Epic patterns, non-obvious scoping constraints uncovered, code-reuse discoveries from code-scanner, duplicate-Epic near-misses that required scope adjustment. > If YES: append to the most appropriate existing file (never create a new file if an existing one fits) using this format: > ### [Short title] > - **Context**: what problem/situation triggered this > - **Insight**: the learned rule, pattern, or gotcha > - **When it applies**: conditions under which this matters > - **Date**: YYYY-MM-DD > - **Ref**: [first 60 chars of the Jira key + VI summary] > Return: file updated/created and summary of entry, OR 'no update required'." **Agent 3 — Instructions** (general-purpose): > "Post-write instructions review. Change summary: > [paste change summary block] > > Check .github/copilot-instructions.md in the project root and ~/.copilot/copilot-instructions.md (global). > Determine if any Epic-drafting rules, guidance, or guardrails are missing because of what this run revealed (e.g., a domain-specific acceptance-criteria pattern, a naming convention for Epic files, a scope-boundary rule that caught you out). > Skip if: the run followed existing conventions with no surprises. > If YES: apply minimal, additive, scoped changes only. > Return: what was changed and why, OR 'no update re …(truncated)