yeaight7/agent-powerups / plugins/dev-vitals/skills/handoff-discipline
handoff-discipline
VerifiedUse when ending a session, handing a task back to the user, or approaching the context limit with work unfinished -- the next session or engineer must be able to resume the work instantly.
Purpose
When ending a session, handing a task back to the user, or preparing to swap to a new context window, you must leave a clean paper trail β exactly what the next session or human engineer needs to resume work instantly.
When to Use
- A task ends (complete or not) and someone else picks it up next
- The context window is nearly full mid-task
- Work is blocked and must pause on an external dependency
Inputs
- The session's actual state: what ran, what passed, what is mid-flight
- The repo's working-tree status
Workflow
-
State the end condition. Explain exactly why you are stopping (e.g., "Task complete", "Blocked on PR", "Context window too large").
-
Leave a breadcrumb. If the task is incomplete, summarize the last successful step, the current failing step, and the exact next command to run. Record discovered constraints and dead ends so the next session doesn't retry them.
-
Commit or stash. Ensure the working directory is clean. Either commit the work, tell the user to commit, or stash it. Do not leave unverified messy state:
git status --short # what is uncommitted? git stash push -m "handoff: <task>" # if not committing -
Link the work. Provide file paths to the modified files or generated artifacts so the next agent/user doesn't have to search for them.
-
Write the handoff summary (a handoff markdown file, or the final message) using this exact structure:
### 1. Goal [1-2 sentences on what we were trying to do] ### 2. State - β Completed: [What works] - π§ In Progress: [What is broken or partial] - π Blockers: [What stopped us] - β οΈ Dead ends: [Approaches tried that failed, and why] ### 3. Next Steps 1. Run `npm test ...` 2. Fix the error in `src/foo.ts` around line X.
Output
- A handoff summary in the Goal / State / Next Steps format
- A clean, committed, or explicitly stashed working tree, with artifact paths linked
Verification
- End condition stated explicitly
- Next command is runnable verbatim by the next session β no "continue where I left off"
- Working tree clean, committed, or stashed β confirmed with git status, not assumed
- Every modified or generated file linked by path
- State section separates completed, in-progress, and blocked honestly
Failure Modes
- Vague resumption β "continue the refactor" instead of the exact failing step and next command.
- Dirty-tree handoff β uncommitted, unexplained changes the next session must reverse-engineer.
- Completed-only reporting β hiding the broken parts makes the handoff a trap.
- Unlinked artifacts β the next agent burns context searching for files you could have named.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |