diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md b/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md index d554b96ed..5f7c665d7 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md @@ -1,72 +1,62 @@ # Compile Epic Context -You are a context-compilation agent. Your job is to read planning artifacts and produce a single, scoped context document for one epic. +**Task** +Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic--context.md`). -## Inputs +**Steps** -You will receive: +1. Read the epics file and extract the target epic's title, goal, and list of stories. +2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief). +3. Pull only the information relevant to this epic. +4. Write the compiled context to the exact output path using the format below. -- **Epic number** — which epic to compile context for -- **Epics file path** — the file containing epic and story definitions -- **Planning artifacts directory** — where PRD, architecture, UX, and other planning docs live -- **Output path** — where to write the compiled context file +## Exact Output Format -## Instructions - -1. **Load the epics file** and extract the definition for the target epic: its title, goal, and story list. - -2. **Scan the planning artifacts directory** for these standard BMAD files: - - PRD (`*prd*`) — product requirements and success criteria - - Architecture (`*architecture*`) — technical design decisions and constraints - - UX/Design (`*ux*`) — user experience and interaction design - - Product Brief (`*brief*`) — project vision and scope - -3. **For each planning doc found**, load it and extract only the sections relevant to this epic. Relevance means: the section describes a constraint, requirement, pattern, or decision that a developer working on any story in this epic needs to know. Skip sections that are about other epics or unrelated features. - -4. **Write the compiled context file** to the output path using the format below. - -## Output format +Use these headings verbatim: ```markdown # Epic {N} Context: {Epic Title} - + ## Goal -{One paragraph: what this epic achieves and why it matters.} +{One clear paragraph: what this epic achieves and why it matters.} ## Stories -{Numbered list of stories in this epic — ID and title only. No details.} +- Story X.Y: Brief title only +- ... ## Requirements & Constraints -{Relevant product requirements, success criteria, and non-functional requirements scoped to this epic. Describe by purpose, not by source document section.} +{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).} ## Technical Decisions -{Architecture decisions, tech stack constraints, API patterns, data models, and conventions relevant to this epic. Include ADR references where applicable.} +{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.} ## UX & Interaction Patterns -{Relevant UX patterns, interaction flows, and design constraints. Omit this section entirely if no UX doc exists or nothing is relevant.} +{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).} ## Cross-Story Dependencies -{Dependencies between stories within this epic, and any dependencies on other epics or external systems. Omit if none.} +{Dependencies between stories in this epic or with other epics/systems (omit if none).} ``` -## Error handling - -- If the epics file does not exist or the target epic number is not found in it, write nothing and report the problem to the calling agent. -- If no planning docs match the expected patterns, write the output file with only the Goal and Stories sections populated from the epics file. Note the absence of planning docs in the Goal section. - ## Rules -- **Scope aggressively.** Include only what a developer working on this epic needs. When in doubt, leave it out — the developer can always read the full planning doc. +- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc. - **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't. -- **No full copies.** Never paste entire planning doc sections. Distill into what matters for implementation. +- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill. - **No story-level details.** The story list is for orientation only. Individual story specs handle the details. -- **No code.** Nothing derivable from reading the codebase belongs here. -- **Keep it compact.** Target 800–1500 tokens. This file will be loaded into quick-dev's context alongside other material. +- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code. +- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material. +- **Never hallucinate content.** If source material doesn't say something, don't invent it. +- **Omit empty sections entirely**, except Goal and Stories, which are always required. + +## Error handling + +- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file. +- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections.