resuming-a-feature
Skill2 starsChanged 12 days agoMITView on GitHub
First action of a fresh session when the user asks to resume, continue, or pick up a planned feature — at any phase: mid-development, mid-review, merge staging, or wrap-up. Skip when no state file exists; there is nothing to resume, so ask what the work is or enter feature-dev-workflow:planning-a-feature. The state file is the resume contract, but a cold session that only knows "read the state file" still has to derive the rest: which recorded facts to trust versus re-verify,…
In this repository19 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- addressing-review-feedbackSkill
- bounding-heavy-commandsSkill
- copilot-review-loopSkill
- developing-a-featureSkill
- drafting-a-releaseSkill
- fanning-out-with-worktreesSkill
- maintaining-architectural-coherenceSkill
- opening-a-pull-requestSkill
- planning-a-featureSkill
- product-epicSkill
- reporting-a-skill-gapSkill
- reviewing-feature-progressSkill
- stacking-dependent-prsSkill
- testing-a-featureSkill
- testing-end-to-endSkill
- writing-code-commentsSkill
- writing-docsSkill
- writing-github-issuesSkill
The file
Files
resuming-a-feature
When to invoke
First action of a fresh session when the user asks to resume, continue, or pick up a planned feature — at any phase: mid-development, mid-review, merge staging, or wrap-up. Skip when no state file exists; there is nothing to resume, so ask what the work is or enter feature-dev-workflow:planning-a-feature.
Why this exists
The state file is the resume contract, but a cold session that only knows "read the state file" still has to derive the rest: which recorded facts to trust versus re-verify, which skill owns each remaining action, and how to re-enter at a phase the development skills' triggers don't name (a feature past active development matches no skill description). Left underivable, the user compensates with a hand-written resume prompt reconstructing what the state file already records. This skill is the protocol; the state file's ## Pending snapshot section is its input.
Workflow
1. Locate the state file
A user-provided path wins. Otherwise search every checkout — state files live on feature branches, so the main checkout usually has none: ls docs/superpowers/states/ in the current directory, then in each worktree listed by git worktree list. Multiple candidates → ask which feature.
2. Read it in full, then the plan and spec
Everything: frontmatter (status, the sub_pr_* configuration, branch/worktree/artifact paths), ## Phases, the ## PRs / worktrees table, ## Contracts, ## Bubble-up log, ## Pending snapshot, the resume checklist. Then the plan and spec at the recorded paths (they may already be torn down late in the lifecycle; that is normal, not drift).
3. Verify before trusting
The state file is authoritative for intent, decisions, pointers, and recorded user configuration; live git/GitHub/filesystem are authoritative for every mutable fact. On disagreement, reality wins — reconcile the state file first (commit and push it) before proposing any mutation.
| Trust from the file | Verify against live sources |
| Plan/spec paths, slug, issue and PR numbers, branch names, worktree paths | Each PR's actual state: gh pr view <num> --json state,isDraft,baseRefName,headRefOid,mergedAt vs the recorded row |
sub_pr_approval / sub_pr_review_loop / sub_pr_target — explicit user answers; don't re-ask | Each issue's open/closed state (gh issue view <num> --json state) |
| Bubble-up resolutions and their propagation records | Each worktree: exists, clean, no unpushed commits (git -C <path> status --porcelain --branch — an ahead count in the header means unpushed commits; no upstream in the header means the branch was never pushed, so everything on it is unpushed) |
The ## Pending snapshot's intent and ordering | Branch existence (git rev-parse --verify <branch>), CI state (gh pr checks <num>) |
Which rows form a stack, and its recorded layer order (the ## Stacks section) | The stack itself, from its one dedicated worktree (never the main checkout): gh stack view --json (order, PR numbers, needsRebase); no layer branch checked out in any other worktree, the main checkout included (git worktree list), except a parallel layer that has not joined yet, which stays in the temporary worktree its row records; gh stack --version works, or stop and ask the user to install it. If the stack exists only as a link on GitHub, with no dedicated worktree, do not adopt it here: adoption rebases and force-pushes the layers. Verify it only from its PRs for now (the PR check above), and propose the adoption as the first mutation in the Step 6 report (feature-dev-workflow:stacking-dependent-prs §Adopting a stack that was built by hand). Verify it from its worktree once it is adopted |
4. Treat the bubble-up log as settled
Its entries record adjudicated decisions with their why. A fresh session's fresh eyes are not new evidence — don't reopen or silently redo them. If one looks genuinely wrong, raise it with the user; never relitigate it unprompted.
5. Route by recorded phase
status: | Re-enter |
planning | feature-dev-workflow:planning-a-feature, at the step the snapshot names |
foundational-wave / consumer-wave | feature-dev-workflow:developing-a-feature Step 4 → feature-dev-workflow:fanning-out-with-worktrees, continuing the recorded wave |
review | The ## Pending snapshot's actions, each through the skill that owns it: retargets, body reconciliation, and ready-flips via feature-dev-workflow:opening-a-pull-request; pre-flip checkpoints via feature-dev-workflow:reviewing-feature-progress; issue closure and reconciliation via feature-dev-workflow:writing-github-issues; teardown via feature-dev-workflow:developing-a-feature Step 7 |
merged | Remaining wrap-up items from the snapshot only (worktree deletion after the unpushed-commit check, teardown). Do not close the epic; that is the user's decision |
Resuming changes who is at the keyboard, not who holds the merge button: feature-dev-workflow:developing-a-feature's merge guard still governs, and no gh pr merge runs beyond what sub_pr_approval / sub_pr_target already configured.
6. Report before mutating
One reconciled summary to the user: the feature, the phase, per-PR reality against the recorded rows, every divergence found and fixed, and the next actions from the snapshot. Then confirm the first mutation — resuming is not standing consent for the backlog.
The Pending snapshot contract (producing side)
Resume quality is determined before a session ends, not after the next one starts. At the end of every work burst — and always when the user signals a pause or a session end — refresh the state file's ## Pending snapshot: the ordered next actions, each carrying what, where, which skill owns it, and what gates it, with enough context that a cold session could execute from the file alone. If the user has to hand-write a resume prompt reconstructing the state, the snapshot failed its job.
Red flags
| Thought | Reality |
| "The row says draft, so it's a draft" | Rows record the past; gh pr view is the present. Verify every mutable fact before acting on it. |
| "The user's resume prompt describes the state, that's enough" | Prompts go stale exactly like rows. Read the file, verify live, reconcile — then act. |
| "This bubble-up decision looks wrong, I'll redo it properly" | It records an adjudication with its why. Raise it with the user if genuinely suspect; don't silently reopen it. |
| "Development is done, so developing-a-feature doesn't apply anymore" | Its merge guard, state-file contract, and Step 7 teardown still govern. Route each remaining atom through the skill that owns it. |
| "I'll work through the snapshot, no need to check GitHub first" | The snapshot was true when written. A human may have merged, retargeted, or commented since. Verify, reconcile, then execute. |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.