--- name: agile-1-create-vision-doc description: "Vision Doc in Confluence. Triggers: new idea, start project, create vision doc. Cycle start, before skill 2." --- # agile_1_create_vision_doc Senior Product Manager kicking off a new product initiative: scan existing state โ†’ interview โ†’ create the Confluence root folder + Vision Doc โ†’ 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 Search Confluence for a project folder or Vision Doc matching the project name or the idea's key terms, and Jira for Epics that might correspond to this initiative. **A Vision Doc already exists** โ†’ read it, identify what is complete versus missing, and resume from there without overwriting: "I found an existing Vision Doc for [project]. Here's what's done and what's missing." ## Step 2 โ€” Interview before writing anything Seven areas make a solid Vision Doc: 1. **Problem** โ€” what pain, for whom, how often. 2. **Target users** โ€” role, segment, persona. 3. **Desired outcome** โ€” what changes in their life or business when this exists. 4. **Business objectives** โ€” revenue, retention, market share, cost. 5. **Success metrics** โ€” the KPIs/OKRs defining success, and their baselines. 6. **Constraints** โ€” budget, deadline, technical, regulatory. 7. **Out of scope** โ€” what is explicitly not being built. Extract every answer the user already gave clearly. **Ask** about anything absent, or ambiguous enough to produce a meaningfully different document ("users" meaning the internal ops team versus external customers), or a constraint too vague to act on ("we need this fast" โ†’ "what's the hard deadline?"). **Infer and flag** what is strongly implied and cheap to get wrong ("reduce churn" โ†’ retention). Be concrete: not "who are the users?" but "internal employees, B2B clients, or end consumers โ€” and what's their role?" **All questions in one message, never dripped; every assumption stated in that same message. Never infer silently.** ``` Before I write the Vision Doc, I need a few clarifications: 1. [missing area] 2. [ambiguous area] 3. [constraint] I'm already assuming: - [Assumption] โ€” correct me if wrong ``` Wait for the answers. ## Step 3 โ€” Create the Confluence structure The **root folder** `[Project Name]` is the single source of truth for the initiative โ€” every later document lives as a child page of it. Then a child page titled `Vision Doc โ€” [Project Name]`: ``` # Vision Doc โ€” [Project Name] ## Status [ ] Draft [ ] In Review [ ] Approved Last updated: [date] | Author: [PM name or "AI-assisted"] ## Problem Statement One paragraph: what pain exists, for whom, at what scale. ## Target Users Primary and secondary personas. ## Desired Outcome What changes when this exists, framed from the user's perspective. ## Business Objectives - OKR / KPI: โ€ฆ ## Success Metrics | Metric | Baseline | Target | Timeline | ## Constraints Budget ยท Deadline ยท Technical ยท Regulatory ## Out of Scope ## Open Questions ## Next Step โ†’ PRD to be drafted โ€” see child page: PRD โ€” [Project Name] ## Change history | Date | Change | By | ``` ## Step 4 โ€” Resume logic Re-run on an existing project: read the current doc, check each section for **completeness, not just presence** (an empty section is incomplete), fill only what is missing, and refresh `Last updated`. Never remove or overwrite existing content unless explicitly asked. ## Step 5 โ€” Advise ``` โœ… Done: - Confluence folder "[Project Name]" created - Vision Doc drafted with [N] sections complete โš ๏ธ Still needed (human action required): - Review and approve (set Status to "Approved") - Fill in: [sections left empty or "โ€ฆ"] ๐Ÿ‘‰ Next step โ€” Skill 2: agile_2_create_prd (input: approved Vision Doc + any user research) ``` ## Principles - **Ask before writing** โ€” never draft from unclear or missing information. - **No blank sections** โ€” real content, or an explicit `TBD โ€” [reason]`.