// Transform vision documents into structured epics that bound story-writing
Code Review Protocol
Coordinate Pairing-mode doer/reviewer sessions through a Markdown blackboard. Use when the user invokes /adversarial-pairing with role and blackboard-path arguments or asks multiple pairing agents to coordinate plan review, implementation, staged code review, and follow-up review rounds without Liza multi-agent mode.
Analyze Liza `.liza/agent-prompts/` and `.liza/agent-outputs/` from a context-engineering perspective: prompt payload shape, context budget use, cacheability, duplicated or missing context, instruction hierarchy, tool-output pressure, role-specific context fit, and prompt-output feedback loops. Use when diagnosing agent context bloat, prompt drift, poor agent handoffs, repeated misunderstandings, excessive tool output, or whether Liza agents received the right information at the right time.
Analyze Liza agents logs
Transform requirements into user stories for coding tasks
Context-efficient delegation to subagents (read-only default, READ-WRITE opt-in)
| name | epic-writing |
| description | Transform vision documents into structured epics that bound story-writing |
Transform a vision document or high-level product requirement into a structured epic — a markdown document, git-tracked, treated with the same rigor as code.
An epic has two audiences: first the teller, then the doer. The Intent Review (Part 1) lets the intent owner verify scope and interpretation in minutes. The Execution Contract (Part 2) gives Story Writers and the Orchestrator everything they need to decompose and implement. Neither section is optional.
The Execution Contract is the primary input to the user-story-writing skill. Each capability section becomes a Story Writer task: the Story Writer reads the epic's Personas, General Information, and the capability section — nothing else. Write accordingly. A capability that requires the Story Writer to re-read the vision to understand what they're building is incomplete.
An epic bounds one cohesive capability area, serving a coherent persona cluster, expected to decompose into 3–8 user stories across its capabilities. It lives one level above user stories. Its job is to answer: what is being built, for whom, and what is explicitly out of scope — not how. It decomposes into capabilities; capabilities decompose into story documents.
Use this skill when:
Scope discipline (two-tier):
In both cases, declare what you read and why in the References section.
Produce a markdown file at the output path. Use the Epic format template.
Skim the source material for obvious splitting signals before deep parsing. A badly-sized epic fans out into N Story Writer tasks before anyone notices the framing was off.
Granularity signals:
| Signal | Diagnosis |
|---|---|
| Scope spans multiple independent persona clusters or unrelated subsystems | Too broad — split at capability boundary |
| Would produce >8 user stories to cover its scope | Too broad — find a natural seam |
| Completion criteria require outcomes across unrelated subsystems | Too broad — each subsystem likely deserves its own epic |
| Description contains conjunctions joining unrelated capabilities ("auth and notifications and reporting") | Too broad — composite epic smell |
| Entire scope is a single user action with one acceptance criterion | Too narrow — this is a story, not an epic |
| Could be implemented in a single coding task without further decomposition | Too narrow — skip the Story Writer stage |
| Would produce fewer than 2 meaningful user stories | Too narrow — merge with an adjacent epic or promote directly |
| Cannot be delivered or validated independently of another epic | Too coupled — reconsider the boundary |
If a single epic's scope spans multiple independent capability areas, flag this — the epic is too broad and needs splitting. This is about epic sizing, not about the number of epics a task produces. When a planner task decomposes a vision document, producing multiple well-sized epics from one task is normal — apply this skill once per epic boundary.
If sizing is ambiguous, flag before proceeding. A wrong cut here is more expensive to fix than a brief hold.
Read the source material. Before writing anything, identify:
Do not start writing until you can answer all five. If you cannot answer one, it becomes an Open Question — not a blank you fill with imagination.
A capability is a user-facing behavior the team can build, test, and hand off to a Story Writer as a bounded unit. It is not a technical module, a sprint, or a story. It is a slice of product behavior.
Each capability must pass the self-containment test defined in the Objective: a Story Writer handed the Personas, General Information, and this capability section can begin writing without reading the vision source.
Capability heuristics:
Story document planning: For each capability, list the story documents it decomposes into. A story document covers one cohesive unit of work a Story Writer can own independently. You are naming documents, not writing stories — the Story Writer does that. Each entry needs only a short title and any known dependency notes.
Write Part 1 before Part 2. The Intent Review is a forcing function: if you cannot write a clear Before/After promise, the epic scope is not yet understood.
Promise (Before/After): State what the product cannot do today and what becomes possible after this epic ships. Plain language, no IDs, no jargon. A non-technical stakeholder should be able to read this and say "yes, that's what I want" or "no, you misunderstood."
Capability Map: One row per capability. The human-facing outcome column restates the capability as a user benefit — not the capability description (which is written for Story Writers), but its plain-language consequence. The source intent column traces back to the vision material. The main exclusion column names the most important thing this capability deliberately leaves out.
Interpretation Decisions: Surface every non-obvious inference from source to epic. The test: if a reasonable reader of the source material might interpret a signal differently, it belongs here. Omit this section only when the epic is a straightforward decomposition with no judgment calls. Mark "Verify? Yes" when the interpretation is consequential — meaning a wrong call here changes what gets built.
Review Questions: Write 3–5 targeted questions the intent owner can answer with a short response. These are not open-ended feedback prompts ("does this look right?") — they are specific verification points ("Is X intentionally out of scope, or should it move into this epic?", "Did we correctly interpret Y as Z?", "Is this the right ownership boundary between EP-NNN and EP-MMM?").
Completion Criteria replace vague success metrics. They are the falsifiable condition that closes the epic: when all story ACs pass, the completion criteria must be satisfied. Write them as observable outcomes, not directions. "Users can create, edit, and delete tasks without data loss" is a completion criterion. "Improve task management" is not. If you cannot write falsifiable completion criteria, the epic scope is not yet understood — surface it as an Open Question.
Personas at the epic level describe who benefits from the whole epic. Capabilities may narrow to specific sub-personas — note this in the capability description where relevant. A useful persona includes environment and skill level when they affect product decisions. Compare: "Operator: a person running the platform" vs. "Ops Engineer: a backend engineer on call who monitors the platform via terminal and alerts and needs concise, machine-parseable output." The second persona constrains every capability under it and tells the Story Writer what conventions to assume.
Out of Scope is not optional. It protects Story Writers from scope absorption and the team from scope creep. Name adjacent capabilities the source implies but this epic deliberately excludes. If it's not named, Story Writers will assume it's included.
Assumptions at the epic level are strategic: they resolve ambiguity in the vision material that would otherwise leave Story Writers unable to bound their own work. They are NOT technical decisions. An assumption that names a data format, protocol, or library is premature solutioning — state the behavioral constraint only.
Confidence discipline:
Open Questions at the epic level are product-level decisions only: personas, scope boundaries, completion criteria, or capability ordering. Technical open questions belong in story documents, not here.
Before submitting for review, verify:
Intent Review (Part 1):
Execution Contract (Part 2):
If self-review reveals issues, fix before submitting.
All IDs use structured prefixes:
| Prefix | Meaning | Example |
|---|---|---|
| EP-NNN | Epic | EP-003 |
| CAP-NNN | Capability (scoped to epic) | CAP-001 |
| C-NNN | External component | C-002 |
| I-NNN-NNN | Interface (composite: I-{component}-{interface}) | I-002-001 |
| NFR-000-N | Non-functional requirement | NFR-000-1 |
| ASM-NNN-N | Assumption (000 = general, NNN = capability) | ASM-000-1 |
| OQ-NNN-N | Open question | OQ-001-1 |
Do not invent new prefixes. If something doesn't fit these categories, it likely belongs in Context or is a sign the epic needs rethinking.
The hardest judgment in epic-writing is staying at the right altitude. Use this table as a check:
| Too low (story territory) | Right level (epic territory) | Too high (vision territory) |
|---|---|---|
| AC: "Given a valid token, when…" | "User can authenticate without re-entering credentials" | "Improve onboarding" |
| "The endpoint returns 200" | "Operator can monitor request health in real time" | "Better observability" |
| "Use PostgreSQL for storage" | "Tasks persist across sessions" | "Reliable data" |
| "Validate email format on blur" | "User receives actionable feedback on invalid input" | "Good UX" |
If a capability description reads like a story, it's too low. Rewrite it as a user-facing behavior. If it reads like a goal in an OKR, it's too high. Narrow it to something a Story Writer can bound.
| Skill | Relationship |
|---|---|
| user-story-writing | Direct downstream consumer. Each capability section is a Story Writer task brief. The Story Writer reads the Personas, General Information, and the capability section — nothing else. Unresolved epic assumptions and Open Questions block story-writing from starting. |
| detailed-spec-writing | Complementary. Epics capture product intent; PRDs capture system requirements. An approved epic can seed a PRD for a capability. |
| spec-review | Downstream. Validates epics against completeness/consistency/testability. |
Pairing mode: All interactive prompts apply. Present the draft epic for human review before writing the file. Human may redirect scope, resolve Open Questions inline, or confirm assumptions.
Liza mode: Epic Writer operates autonomously within task scope. When a planner task decomposes a vision document, the planner applies this skill once per epic boundary it identifies. Producing multiple epic artifacts from a single vision source is normal pipeline behavior — the "flag for splitting" guidance in Size applies to individual epics that are too broad, not to the planner's decomposition of a vision into multiple epics.
| Pairing Prompt | Liza Behavior |
|---|---|
| "Source material spans multiple capability areas — split?" | Applies to a single epic that's too broad. When decomposing a vision into multiple epics, multiple capability areas across epics is expected — flag only if a single epic spans unrelated areas |
| "Epic would produce >8 stories — where to split?" | Find the natural persona or subsystem seam; flag split rationale in Context |
| "Epic would produce <2 stories — merge or promote?" | Flag to Orchestrator via BLOCKED with merge/promote recommendation |
| "This assumption is LOW confidence — resolve?" | Surface in Assumptions section; blocks story-writing until resolved by human |
| "Adjacent epic may conflict — check?" | Read adjacent document, declare in References, note in Context |
| "Cannot identify a clear persona for this epic" | Surface as Open Question — an epic without a persona cannot produce well-bounded stories |
| "Cannot write falsifiable completion criteria" | Surface as Open Question — scope is not yet understood |