to-epics

To Epics

Quick Start

Use this skill after a target architecture document exists or when the user explicitly wants architecture work translated into epics.

Do not automatically create epics from analysis alone. Before creating or updating an epic file, require the user to provide:

• Target architecture to link to
• Epic name
• Phase
• Epic description
• Main capability

If any required input is missing, ask for it and stop before writing the epic.

Output Location

Create epics in the private lab root under requirements/<name-of-target-architecture>/.

Use the target architecture folder name as <name-of-target-architecture> unless the target architecture document defines a clearer document name. Normalize it to the same slug style used for folders.

<private-lab-root>/
├── requirements/
│   └── <target-architecture-slug>/
│       └── <epic-slug>.md
└── solution-architectures/
    └── <target-architecture-slug>/
        ├── 08-phase-e-solution-building-blocks.md
        └── target-architecture-document.md

Use templates/epic-template.md for the epic file. Preserve the two opening tables: the document metadata table first, followed by the Epic Overview table.

Workflow

1. Ask the user which target architecture to link the epic to.
   • If the user named a target architecture, confirm the exact folder or document path before continuing.
   • If the user did not name one, search for solution-architectures/*/target-architecture-document.md, present the candidates, and ask the user to choose.
   • Do not create an epic until the user has selected or confirmed the target architecture linkage.
2. Read the target architecture document and relevant section files, especially 08-phase-e-solution-building-blocks.md, roadmap themes, gap analysis, governance actions, risks, and open questions.
3. Ask the user for the epic name, phase, epic description, and main capability if not already provided.
4. Ask for reference links:
   • Main capability link
   • Main L2 solution architecture link
   • Existing Jira item URL/key, if any
   • Existing Confluence page URL, if any These references are optional except when the user can identify the linked artifact. Use TBD when the user does not provide a link. Use the linked document title as the Markdown link label whenever possible. For local markdown files, derive the title from the first # heading; otherwise use the filename without extension. For Jira and Confluence links, use the issue key/page title when the user provides it; otherwise ask for the title or use TBD.
5. Start a grill-me clarification session using ../grill-me/SKILL.md.
   • Focus the session on whether the epic has enough detail to be useful for delivery planning.
   • Ask one question at a time and wait for the user's answer before continuing.
   • Cover scope, out of scope, assumptions, dependencies, business requirements, visual design, solution design, Site Reliability Engineering, architecture impact, open questions, and glossary-sensitive terminology.
   • Use ../ubiquitous-language/SKILL.md during the session when terms are vague, overloaded, missing from GLOSSARY.md, or important enough to become shared domain language.
   • Continue only when the required epic fields are confirmed and remaining unknowns are explicitly captured as open questions or TBD.
6. Confirm the target architecture linkage:
   • Target architecture document path
   • Requirements output folder: <private-lab-root>/requirements/<name-of-target-architecture>/
   • Phase
   • Main capability
   • Main capability link, or TBD
   • Main capability link title, derived from the linked capability document title where possible
   • Main L2 solution architecture link, or TBD
   • Main L2 solution architecture link title, derived from the linked solution architecture document title where possible
   • Jira item reference, if provided
   • Jira link title, normally the issue key or issue summary
   • Confluence page reference, if provided
   • Confluence link title, normally the page title
   • Roadmap theme, gap, decision, governance action, or architecture section the epic supports
   • Any known dependencies or sequencing constraints
7. Validate terminology before writing the epic:
   • Locate <private-lab-root>/GLOSSARY.md.
   • Check the epic name, description, main capability, scope terms, application names, data objects, integrations, and business requirements against the glossary.
   • If GLOSSARY.md is missing, or if important terms are missing, ambiguous, or inconsistent, use ../ubiquitous-language/SKILL.md to create or update <private-lab-root>/GLOSSARY.md before creating the epic.
   • Do not write real-company terminology into this public toolkit repository; update the private lab root glossary.
8. Create requirements/<name-of-target-architecture>/<epic-slug>.md from the template. Preserve the document metadata table and the Epic Overview table. Do not overwrite an existing epic unless the user explicitly asks to update it.
9. Update the target architecture linkage:
   • Add or update the epic's titled block in the ## Epics To Build section of 08-phase-e-solution-building-blocks.md when that file exists.
   • Add or update the same titled block in a ### Epics To Build subsection of the Phase E section in target-architecture-document.md when that subsection exists.
   • Link the epic file with a relative markdown link from the target architecture document folder to the requirements file.
10. Summarize what was created, which grill-me questions materially shaped the epic, which glossary terms were confirmed or added, and which target architecture sections the epic traces to.