to-issues

# To issues Turn an approved specification into a dependency graph of implementation-ready GitHub Issues. The goal is not to create a checklist of technical layers. The goal is to create small, meaningful units of product behavior that can be implemented and verified independently. ## Process ### 1. Gather context Read: - the complete approved spec; - the parent GitHub Issue when one exists; - relevant project instructions; - enough of the existing codebase to understand integration points and current conventions. Do not reopen product decisions already settled by the spec. ### 2. Identify implementation slices Prefer vertical slices. A good issue delivers a narrow but complete behavior across whichever layers are required. Prefer: - create a session end-to-end; - edit an officer end-to-end; - reveal a solution end-to-end. Avoid horizontal decomposition such as: - build database; - build backend; - build frontend. A completed issue should produce something independently testable, demonstrable, or structurally necessary for later work. ### 3. Size issues for agents Each issue should: - fit comfortably in one fresh agent context; - have one clear responsibility; - avoid unrelated cleanup; - contain enough context to execute without guessing; - have observable acceptance criteria. Split an issue when it contains multiple independently useful behaviors. Merge issues when separating them would create artificial coordination without useful isolation. ### 4. Determine dependencies For every issue identify genuine blockers. Do not create a linear chain unless the work truly requires one. Independent issues should remain independent so they may be implemented concurrently. Think of the result as a dependency graph: ```text Parent spec ├── Issue A ├── Issue B │ └── Issue D └── Issue C └── Issue E ``` An issue is ready when all of its blockers are complete. ### 5. Handle broad refactors carefully Vertical slices are the default. For a mechanical change whose blast radius makes independent vertical slices impossible, use an expand-migrate-contract sequence: 1. Expand: introduce the new form without removing the old one. 2. Migrate: move callers in bounded batches. 3. Contract: remove the old form after migration is complete. Keep the repository working between stages whenever practical. ### 6. Present the proposed breakdown Before creating GitHub Issues, show: 1. issue title; 2. what it delivers; 3. acceptance criteria; 4. blockers; 5. relationship to the parent spec. Ask for approval when the user has not already explicitly authorized creating the issues. ### 7. Create GitHub Issues Create blockers before dependent issues so dependency references can use real issue numbers. Use this structure: ## Parent Reference the parent spec or parent GitHub Issue. ## What to build Describe the behavior delivered by this issue from the project's perspective. ## Acceptance criteria - [ ] Observable criterion - [ ] Observable criterion ## Blocked by Reference blocking issues. Use `None` when the issue can start immediately. ## Notes Include only implementation constraints or decisions needed to preserve the spec. Omit this section when unnecessary. ### 8. Connect the graph When GitHub supports the required relationship, use native sub-issue or dependency relationships. Otherwise reference related issue numbers explicitly in the issue body. The parent should make it easy to discover the complete implementation set. ## Rules - The approved spec is the contract. - Do not silently expand scope. - Do not invent requirements. - Prefer vertical slices. - Do not create one issue per technical layer. - Do not include exact file paths unless they are a required constraint. - Do not prescribe implementation details the spec does not require. - Preserve project terminology. - Acceptance criteria describe behavior, not implementation steps. - Dependencies must represent real blockers, not preferred ordering. - Do not close or modify the parent issue unless explicitly requested. ## Completion The breakdown is complete when: - every requirement in the spec is covered; - every issue has a clear outcome; - every issue has verifiable acceptance criteria; - dependencies are explicit; - no issue requires unresolved product decisions; - each issue can be understood by a fresh implementation agent. The resulting issues are ready for `implement-issue`.