--- name: agile-6-create-epics description: "Epics in Jira from Roadmap. Triggers: create epics, set up Jira for MVP. After skill 5, before skill 7." --- # agile_6_create_epics Product Manager + Tech Lead structuring work in Jira so it is ready for Story writing: scan โ†’ interview on anything ambiguous โ†’ create/update Epics linked to Confluence โ†’ advise. ## Confluence structure (canonical โ€” identical across all agile-skills) Every page is a child of the root folder created by `agile-1`. Read this tree before creating any page; never duplicate one that exists. ``` ๐Ÿ“ [Project Name] (root โ€” agile-1) โ”œโ”€โ”€ ๐Ÿ“„ Vision Doc โ€” [Project] (agile-1) โ”œโ”€โ”€ ๐Ÿ“„ PRD โ€” [Project] (agile-2) โ”œโ”€โ”€ ๐Ÿ“„ Design Brief โ€” [Project] (agile-3 BRIEF) โ”œโ”€โ”€ ๐Ÿ“„ Specs UI โ€” [Project] (agile-3 INTEGRATE) โ”œโ”€โ”€ ๐Ÿ“„ ADR โ€” [Project] (agile-4; current architecture state) โ”œโ”€โ”€ ๐Ÿ“„ Decision Log โ€” [Project] (agile-5; register, one row per decision) โ”‚ โ””โ”€โ”€ ๐Ÿ“„ Decisions D001โ€“D099 โ€” [Project] (full entries by ID range: D100โ€“D199, โ€ฆ) โ”œโ”€โ”€ ๐Ÿ“„ Working Agreements โ€” [Project] (agile-5 creates ยท agile-15 writes; rules in force: process, planning, operator, ops) โ”œโ”€โ”€ ๐Ÿ“„ Roadmap โ€” [Project] (agile-5 โ€” INDEX only) โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ Parking Lot โ€” [Project] (agile-5; unscheduled and rejected ideas) โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ MVP โ€” [Project] (agile-5; an iteration page) โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ“„ Sprint 1 โ€” [Project] (agile-9 plans ยท agile-8 backlog ยท agile-15 closes) โ”‚ โ””โ”€โ”€ ๐Ÿ“„ Iteration N โ€” [Project] (agile-5 ITERATION) โ”‚ โ””โ”€โ”€ ๐Ÿ“„ Sprint N โ€” [Project] โ”œโ”€โ”€ ๐Ÿ“ Retrospectives โ€” [Project] (container: page or Confluence folder, agile-15; one Retro page per sprint) โ”œโ”€โ”€ ๐Ÿ“ Closeouts โ€” [Project] (container: page or Confluence folder, agile-13; sibling of Retrospectives, never inside it) โ””โ”€โ”€ ๐Ÿ“ Extras โ€” [Project] (folder; Debt Register (agile-15) + every page this tree does not name) ``` **Page placement.** Before creating a page, pick its parent from this tree and pass that parent's page id. Under the Roadmap sit only `Parking Lot`, `MVP` and `Iteration N`; under an `MVP` / `Iteration N` page sit only its `Sprint N` pages. A closeout goes in `Closeouts`, a retro in `Retrospectives`, and any page the tree does not name (audit, coverage matrix, investigation, one-off report) in `Extras`. Reuse an existing folder whatever its exact title (`Extras` or `Extras โ€” [Project]`); create it under the root only when absent. After creating, read the page back: a wrong `parentId` is fixed by moving the page (`mcp__atlassian__updateConfluencePage` with `parentId`), never by creating a second copy. **Page layouts.** Every page keeps the `##` headings below, in this order, and no others. A heading never carries a status, a date or a skill name, so a section is found by its name. Status lives in the page's `## Properties` (the Roadmap's `## Status` line); history lives in `## Change history` (`Date | Change | By`, one row per edit) and in the edit's version message, never in a status line, a heading or a table cell. Planning-time text is rewritten to the outcome when the sprint closes, not left beside it. agile-planning skills read the field-level templates from `agile-5-roadmap`; other skills use the headings and columns below. | Page | `##` headings, in order (table columns in brackets) | |---|---| | Roadmap | Status ยท Guiding principle ยท Iterations ยท Progress ยท Parking lot ยท Next step ยท Change history | | MVP / Iteration N | Properties ยท Goal ยท Success criteria ยท Epics in scope ยท Sprints ยท Scope changes ยท Dependencies and risks ยท Feedback carried in ยท Research record ยท Closing summary ยท Change history | | Sprint N | Properties ยท Goal ยท Scope ยท Decisions ยท Backlog ยท Build order ยท Success criteria ยท Risks ยท Conclusion ยท Notes ยท Change history | | Decision Log | Register (ID ยท Alias ยท Date ยท By ยท Title ยท Status ยท Scope ยท Supersedes / Amends ยท ADR ยง ยท Entry) ยท Change history | | Decisions D###โ€“D### | one `## D### โ€” ` per decision: Decision ยท Why ยท Alternatives rejected ยท Consequences ยท Supersedes / Amends ยท Source | | Parking Lot | Ideas (Idea ยท Raised ยท Why parked ยท Earmark ยท Link) ยท Rejected (Idea ยท Date ยท By ยท Why) ยท Change history | | Working Agreements | Rules in force (Rule ยท Kind ยท Since ยท Source ยท Applies to) ยท Retired (Rule ยท Retired ยท Why) ยท Change history | | Debt Register | Open (Item ยท Source ยท Jira ยท Size ยท Target) ยท Closed (Item ยท Closed ยท How) ยท Change history | | Retrospectives / Closeouts | Index (one row per report) when the container is a page; a Confluence folder has no body and lists its children itself | | Vision Doc ยท PRD ยท Design Brief ยท Specs UI ยท ADR | the template in the owning skill, ending with Change history | | Retro ยท Closeout | the template in the owning skill (written once) | **One fact, one home; every other page links to it.** Tickets, points and statuses โ†’ Jira. Verdicts and severity counts โ†’ the Closeout. Lessons โ†’ the Retro. Current architecture โ†’ the ADR. Decision text โ†’ the Decision Log; elsewhere only its ID and title. Sprint figures โ†’ the Sprint page's Properties, rolled up into its Iteration page's `## Sprints` and the Roadmap's `## Progress` **in the same run** that changes them. A dated snapshot that quotes a figure beside a link to its home (a Retro's velocity line, a verdict as the label of a Closeout link) is allowed; a second copy that someone maintains is not. Size budgets, counted on the rendered text (markup excluded): Roadmap โ‰ค 10k characters, MVP / Iteration page โ‰ค 30k, Sprint page โ‰ค 50k. **A drifted page is fixed, not extended.** A page that breaks its layout โ€” other headings, a changelog in a status line, one fact in several places, contradictory figures, over budget, a page under the wrong parent โ€” is never patched in its old shape and never ignored. Write your own change in the layout, then plan the fix: list the drift and propose `agile-5-roadmap` RESTRUCTURE before finishing, and run it when the user agrees. ## Step 1 โ€” Scan existing state Read the **Roadmap index** to find the current iteration, then open its `MVP โ€” [Project]` / `Iteration N โ€” [Project]` child page and read the **Epics in scope** table there โ€” the index itself only links to it. Read **ADR ยง11** for complexity estimates and dependencies. Search Jira for Epics already created (by name, label, or Confluence link), and for each Epic in scope determine whether it exists and, if so, its current state. Report before doing anything, then ask "Shall I proceed with this plan?": ``` Epic status for [Project Name]: | Epic | In Jira? | Jira status | Action needed | |------|----------|-------------|---------------| | [Epic 1] | โœ… Yes | In Progress | No action โ€” already active | | [Epic 2] | โœ… Yes | To Do | Review description, may need update | | [Epic 3] | โŒ No | โ€” | Will create | ``` **No approved Roadmap โ†’ stop:** "I can't find an approved Roadmap for this project. Please complete skill 5 first." ## Step 2 โ€” Interview for Epic-level clarity Per Epic to create or update: a short action-oriented **name** devs will recognise ("User Authentication", "Dashboard MVP"); a one-sentence **goal** naming the user problem it solves; the **scope boundary**, in and out, which is what stops scope creep at Story-writing time; **Epic-level acceptance criteria** (high level โ€” Stories carry the detail); **dependencies** on other Epics or external systems; the **owning team**; and **labels** for filtering. **Ask** when a name from the ADR is too vague to be a Jira card ("Auth stuff"), when two Epics have a blurry boundary ("User Profile" vs "Account Settings" โ€” "where does one end and the other begin?"), when ownership is unspecified, or when an Epic has an implicit dependency nobody listed. **Infer and flag** a goal derivable from a detailed ADR description, a dependency obvious from the ADR data model ("Notifications requires the User model from Auth"), or labels implied by the Roadmap section (an MVP Epic โ†’ label `mvp`). **Only ask about the genuinely unclear Epics** โ€” never re-ask for ones the ADR already defines well. All questions in one message, every assumption stated. **Never infer silently.** ## Step 3 โ€” Create or update Epics in Jira **Summary:** `[Epic name] โ€” [Project Name]`. **Labels:** `[project-slug]`, `[iteration]`, `[layer]`. **Status:** `To Do`. **Assignee:** the owning team or person when known. ``` ## Goal [One sentence: the user problem completing this Epic solves] ## Scope **In scope:** โ€ฆ **Out of scope:** โ€ฆ ## Epic-level acceptance criteria - [ ] [Criterion] ## Dependencies - Depends on: โ€ฆ | Blocks: โ€ฆ ## References Roadmap ยท PRD ยท ADR ยท Specs UI (Confluence links) ``` - **Create in dependency order** โ€” never create Epic B before the Epic A it depends on. - **An existing Epic with outdated content is updated, never duplicated.** - **Never delete an Epic.** Out of scope โ†’ add a comment explaining why and transition to `Won't Do` / `Cancelled`, after user confirmation. - Link each Epic back to the Confluence Roadmap via a remote link or a description reference. ## Step 4 โ€” Update the MVP/Iteration page Update the `## Epics in scope` table on the current `MVP` / `Iteration N` page โ€” **not** the Roadmap index, since epic-level detail lives on the iteration page: `| Epic | Jira | Why | Complexity | Owner | Sprint | Status |` This keeps the two in sync: the child page is the human-readable view of what is in Jira, and the Roadmap index just links to it. ## Step 5 โ€” Resume logic Re-scan live Jira Epic statuses โ€” never assume the previous state still holds. Create only what is still missing; update only Epics whose description has drifted from the Roadmap/ADR; re-sync the Epics-in-scope table with current links and statuses; report what changed versus what was already correct. ## Step 6 โ€” Advise ``` โœ… Done: - [N] Epics created in Jira: [keys] ยท [N] already existed and were reviewed - MVP/Iteration page Epics table updated with Jira links โš ๏ธ Still needed (human action required): - Assign owners to: [Epics without assignees] - Resolve scope boundary questions: [if any remain] - Validate dependency order with the Tech Lead ๐Ÿ‘‰ Next step โ€” Skill 7: agile_7_create_stories โ€” start with the Epic that has no blocking dependencies. Input: Jira Epic key + the Specs UI page for the relevant screens. ``` ## Principles - **Ask before writing** โ€” clarify vague names, blurry scope boundaries, and ownership first; all questions in one message, every assumption stated. - **Create in dependency order**, and never duplicate an existing Epic โ€” update it. - **Never delete an Epic** โ€” `Won't Do` / `Cancelled`, with a comment and user confirmation. - **Confluence and Jira stay in sync** โ€” every Epic links back on the MVP/Iteration page.