feat(skills/product-epic): add standalone epic-scoping skill

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-dev-workflow",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Make AI feature development visible and reviewable, from spec to shipped PRs.",
   "author": {
     "name": "Ægir Máni Hauksson",

README.md

@@ -35,6 +35,7 @@ It is also the faster path. Breaking the feature into independent PRs lets the m
 | `writing-docs` | A structurally-complete feature changed public-facing docs (README, usage guide, tutorial, API/reference). Writes them to an OSS-grade bar and verifies a reader can use them via a fresh-reader test; defers docstrings, release notes, and specs to their owning skills. |
 | `opening-a-pull-request` | About to `gh pr create`/`edit`. Draft and ready body templates, issue-linking keywords. |
 | `maintaining-architectural-coherence` | Work split across PRs/agents/waves must read as one author. Invoked when agreeing conventions before parallel work, and when reviewing the merged union for structural, interface, naming, and vocabulary drift. |
+| `product-epic` | Standalone, upstream of the flow. A product manager has a rough epic — an idea, a few bullets, a draft — that must be scoped and clarified before an engineer can design against it. Surfaces the gaps with a fresh-reader test, refines them with the PM (challenging scope and feasibility), and files the result. |
 | `drafting-a-release` | Standalone (not part of the feature flow). About to cut a release: drafts curated release notes that explain the why, proposes the version, and gates `gh release create` on the user. |
 
 ## How it works

skills/product-epic/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: product-epic
+description:
+  Use when scoping, refining, or clarifying a product-level epic — a rough
+  idea, a few bullets, or an early draft — so an engineer can pick it up to
+  design an implementation against, or when judging whether an epic is ready
+  to hand to engineering.
+---
+
+# product-epic
+
+A product epic is the artifact an engineer reads to start designing a solution, and the artifact the wider team reads to understand why the work matters. This skill takes whatever a product manager has — a rough idea, a few bullets, an early draft — and drives it to a coherent epic where every unknown is either resolved or explicitly marked for confirmation, then files it as an issue in the repo the user names.
+
+This skill is standalone. Nothing in the feature-development flow routes into it, and it routes into nothing except `feature-dev-workflow:writing-github-issues` to land the result. It sits upstream of `feature-dev-workflow:planning-a-feature`, which is where an engineer designs the solution against a ready epic. Invoke it whenever an epic needs scoping or a readiness check.
+
+## Core principle: readiness is proven by a reader, never asserted
+
+You cannot judge whether an epic is ready by re-reading your own draft. You hold the whole idea in your head, so it always reads clearly to you, and that judgment is worthless for finding gaps. The test is a reader who has only the epic text. This is the same Iron Law as `feature-dev-workflow:writing-docs`: no claim of readiness without a fresh reader passing first.
+
+The principle has a second half. **Nothing unconfirmed is written as fact.** Every line in the epic is either something the PM decided or something the team or codebase confirmed. Anything else is an open confirmation, marked as such — never a default you invented and dressed up as settled.
+
+## Two readers
+
+- **The engineer** who must design the implementation. From the epic alone, can they design a solution, or do they hit an unknown they would have to guess at? This is the primary gate.
+- **The wider team / stakeholder.** From the epic alone, do they understand the user problem, who it is for, and why it is worth doing now?
+
+## Challenge, don't transcribe
+
+A product epic is not a transcription of the PM's first framing. Interrogate it on two fronts.
+
+**Scope versus usability.** The narrowest scope that solves the user problem and the most usable or valuable solution often pull apart. Surface the tension, lay out the candidate cuts, and let the PM choose — this is the PM's call, not yours. Record the chosen cut and the reasoning for it in the epic, so a later reader knows the scope was deliberate and why this candidate won.
+
+**Feasibility honesty.** Is a requirement confirmed feasible at the engineering level, or is it an assumption? An unconfirmed assumption is never written in as fact. It becomes an open confirmation task — "confirm X is feasible before this epic is ready" — owned by someone.
+
+## Readiness bar
+
+Ready does not mean every question is answered. It means **no surprise blockers**: every unknown a fresh engineer would hit is either resolved in the epic or sits in the `## Open confirmations` checklist as an owned task to close before design. Everything is either sorted or marked for confirmation. A named, owned confirmation is fine; an unconfirmed item written as settled fact is not.
+
+## The loop
+
+1. **Take what the PM has, and read it for decided-versus-assumed.** Get the raw epic and the repo it will land in. Do not start filling gaps. First separate what the PM has actually decided from what is assumed or missing.
+
+2. **Prime: sweep the dimensions and the two challenges.** Walk the draft against the readiness dimensions — problem, value, target users, success criteria, scope and non-goals, constraints, dependencies, risks — and the two challenges above. This produces a candidate gap list that seeds the conversation. It does not decide readiness, and you do not fill the gaps from it yourself.
+
+3. **RED — run the readers, do not imagine them.** Dispatch a fresh subagent per reader, given only the current epic text and that reader's job:
+   - engineer: design an implementation against this; list every point where you are blocked or would have to guess.
+   - stakeholder: what is the problem, who is it for, why is it worth doing, and what can you not answer?
+
+   Record their blockers verbatim. Those blockers are the missing items. If both readers pass with nothing blocking, the epic is already coherent — go to step 7. If you genuinely cannot dispatch a subagent, simulate the reader using only the words on the page and nothing you know from the conversation, and treat the result as provisional: a real fresh-reader pass is still owed before the epic is called ready.
+
+4. **GREEN — brainstorm the gaps with the PM, one at a time.** Take each blocker to the PM and either resolve it or record it as a confirmation task. Do not invent the answer; a default you made up is not a resolution. Two moves apply here:
+   - a scope-versus-usability collision: present the candidates, the PM decides, you record the cut and the reasoning.
+   - an unconfirmed feasibility assumption: an owned confirmation task in `## Open confirmations`.
+
+   Ask one question at a time, as in `superpowers:brainstorming`. Refine the epic to the quality bar of `feature-dev-workflow:writing-docs`: precise, every sentence earns its place, no marketing fluff.
+
+5. **Re-run the readers** until the engineer hits no unflagged blocker and the stakeholder understands the why. Readiness is what the readers prove, not what you assert.
+
+6. **REFACTOR — cut anything no reader needed.** Length is justified only by a question a reader actually had.
+
+7. **Land it.** Fill the template, then hand the body to `feature-dev-workflow:writing-github-issues` to create the epic (label `epic`) in the repo the PM named. That skill owns the confirmation gate, the label, and the assignee.
+
+## Template
+
+One template carries the shape and the per-section guidance:
+
+- `${CLAUDE_PLUGIN_ROOT}/skills/product-epic/templates/product-epic.md`
+
+Fill each section per its `<!-- -->` guidance. The detailed implementation design is deliberately not part of it — that is the engineer's downstream work in `feature-dev-workflow:planning-a-feature`. The epic carries solution direction only if it helps frame the problem, and an engineer may flesh it out after conception. Keep the epic project-agnostic in the same way the skill is: it describes a user problem and the value of solving it, not a specific stack.
+
+## Anti-patterns
+
+- **Judging the epic ready by re-reading your own draft.** You wrote it, so it reads clearly to you; that is the one judgment that cannot find a gap. Only a fresh reader with only the text can.
+- **Inventing answers and writing them as decided.** A format, a metric, an SLA, or a flow you made up is not a decision the PM made. It is either resolved with the PM or an open confirmation. "Sensible default" is the tell.
+- **Making the scope call yourself.** Scope versus usability is the PM's decision. Your job is to surface the tradeoff and the candidates, then record the choice and its reasoning.
+- **Stripping the open confirmations to make it look finished.** A clean-looking epic with the unknowns hidden is worse than an honest one with them named — engineering builds against the hidden guesses, and the failure surfaces after launch instead of before design.
+- **One-shotting the epic without asking the PM anything.** Filling gaps from your own judgment skips the person who holds the answers. Ask.
+- **Designing the implementation.** This skill gets the epic ready to design; it does not design. Detailed implementation is downstream and engineer-owned.
+
+## Red flags
+
+| Thought | Reality |
+|---------|---------|
+| "It reads clearly to me, it's ready" | You hold the whole idea in your head. Run a fresh engineer on the text alone; your read proves nothing. |
+| "I'll fill the gaps with sensible defaults" | A default you invented is not a PM decision. Resolve it with the PM, or mark it an open confirmation. |
+| "Engineers hate open questions, I'll just decide" | A named, owned confirmation is honest. A hidden guess makes them build the wrong thing under a deadline. |
+| "The narrower scope is obviously right, I'll cut it" | Scope versus usability is the PM's call. Surface the candidates, let them choose, record the why. |
+| "We're short on time, just make it ready" | Time pressure does not lower the bar. Readiness is the fresh-reader test, not how finished it looks. |
+| "I'll write the implementation so engineering can start faster" | The epic is for designing against, not the design itself. Detailed implementation is the engineer's downstream job. |

skills/product-epic/templates/product-epic.md

@@ -0,0 +1,88 @@
+<!--
+product-epic template. Fill each section per its guidance, then hand the body to
+feature-dev-workflow:writing-github-issues to file it (label: epic).
+
+Two rules govern everything below:
+1. Every line is either something the PM decided or something the team/codebase
+   confirmed. Anything else goes in "Open confirmations" — never written here as fact.
+2. The epic is ready when a fresh engineer, given only this text, hits no blocker
+   that isn't already named in "Open confirmations", and a fresh stakeholder
+   understands the problem and why it matters.
+
+GitHub doesn't render HTML comments, so leaving this guidance in place is harmless.
+-->
+
+# <Title: a human-readable headline of the user value, not a slug>
+
+## Value proposition
+
+<!-- One short paragraph: who this is for, what they can do once it ships that they
+can't today, and why that matters. This is the line the wider team reads to understand
+why the work is worth doing. No solution detail here. -->
+
+## Problem
+
+<!-- The user problem and why it matters now. What is broken, missing, or costly for
+the user today, and what signal says it's worth solving (demand, churn, an obligation).
+State the problem, not the solution. -->
+
+## Target users
+
+<!-- Who specifically has this problem. If more than one type of user is affected and
+they need different things, name each — conflating them is how scope drifts. -->
+
+## User stories and acceptance criteria
+
+<!-- One or more "As a <user>, I <goal> so that <value>" statements. Under each, list
+acceptance criteria as verifiable yes/no conditions a reviewer could check at done-time
+("X is visible when Y", not "the experience is great"). Criteria you can't yet write
+because a decision is open belong in Open confirmations, not invented here. -->
+
+## Success metrics
+
+<!-- How we'll know it worked, measurably. Each metric is a number or an observable
+state, not an aspiration. If the target value isn't decided, say so and add it to Open
+confirmations rather than guessing one. -->
+
+## Scope and the scope decision
+
+<!-- What the first version includes. Then the decision: name the cut you chose and WHY
+you chose it over the alternatives. If a narrower scope and a more usable/valuable cut
+pulled apart, this is the PM's recorded decision and its reasoning, so a later reader
+knows the boundary was deliberate. -->
+
+## Non-goals
+
+<!-- What this explicitly does NOT cover, so it doesn't creep in silently. Each non-goal
+is a thing a reader might reasonably assume is included; call it out and, where useful,
+say whether it's a deliberate "never" or a "not yet". -->
+
+## Constraints and dependencies
+
+<!-- Known constraints this must respect, and anything outside this work it depends on
+(another team, a system, an external input). A dependency that's only assumed available
+is an Open confirmation, not a stated fact. -->
+
+## Risks
+
+<!-- What could go wrong — for users, for the business, technically — and the severity.
+A risk that needs a mitigation decision before design is also an Open confirmation. -->
+
+## Solution direction (optional)
+
+<!-- High-level direction ONLY if it helps frame the problem or bound the scope. The
+detailed implementation is the engineer's downstream job (feature-dev-workflow:planning-a-feature)
+and is deliberately not required here. An engineer may fill this in after conception.
+Do not invent a technical design to make the epic look complete. -->
+
+## Open confirmations
+
+<!-- The checklist of everything that must be confirmed before this epic is ready for an
+engineer to design against. Every unknown surfaced during refinement lives here rather
+than as an invented answer above. Each item names what must be confirmed and who owns it.
+The epic is "coherent" when this list is honest and complete; it is "ready to design"
+when this list is empty. -->
+
+- [ ] <Confirm X is feasible at the engineering level> — owner: <who>
+- [ ] <Confirm whether this needs design / specialist input> — owner: <who>
+- [ ] <Confirm the open decision: ...> — owner: <who>