From 66a41c7a597d67b5fc950f3d41fac6a803743643 Mon Sep 17 00:00:00 2001 From: Gavin Staniforth Date: Mon, 31 Aug 2026 10:28:23 +0100 Subject: [PATCH] docs: add mention of using github issues for larger work --- task-starting.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/task-starting.md b/task-starting.md index 3ecb059..70ef9b3 100644 --- a/task-starting.md +++ b/task-starting.md @@ -13,3 +13,23 @@ When starting a new task or prompt that will involve code changes inside a git r Always ask — do not infer the answer from the branch name or recent activity. 4. **Apply once per task, not per tool call.** This check runs at the start of a new task. Once the base branch is established for the current task, proceed without re-asking on follow-up prompts within the same task. + +## Large multi-phase work: epic + phase issues + +When a task is too big for one or a few PRs — a migration, a version-upgrade +ladder, a staged rollout, anything spanning many PRs over weeks — suggest +tracking it as GitHub issues before starting implementation: + +1. **One issue per phase**, each a self-contained, actionable checklist sized + to one or a few PRs, with explicit exit criteria at the end. +2. **One tracking epic issue** that carries the overall strategy, any + standard per-step procedure (so it isn't repeated in every phase issue), + and a task-list of the phase issues (`- [ ] #NN`) so GitHub auto-tracks + progress as they close. +3. **A dedicated label** (create it if needed) grouping the whole series. +4. Cross-link: each phase issue's opening line references the epic. + +Create the issues with `gh issue create --body-file` (draft bodies as local +scratch files first — they are local-only context per the planning rules). +Confirm with the user before creating issues; once agreed, create the full +series in one go rather than one at a time.