handoff-23822f — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited handoff-23822f (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Generate a handoff document capturing the session state that is not visible from the codebase alone: intent, decisions, rationale, failed approaches, and next steps. The codebase shows what changed. The handoff explains why and what's next.
If arguments are provided ($ARGUMENTS), focus the handoff on that specific aspect of the session. Otherwise, generate a full-session handoff.
!ls -1t handoffs/*.md 2>/dev/null | head -5
If previous handoffs exist above, read the most recent one and reference it at the top of the new handoff under a "Previous Session" heading.
Carryover rule: the "Previous Session" note must restate any context from earlier sessions that is still live — open questions, unresolved bugs, standing constraints, conventions being followed — not merely link to the previous file. Each handoff must be self-sufficient: a session reading only the newest handoff should have everything still relevant. Context that is no longer live should be dropped, so stale items do not propagate forever.
Retention: if more than ~10 handoffs have accumulated in handoffs/, suggest to the user that older ones be archived or deleted — superseded handoffs add noise when listing and resuming.
No discussed topic disappears. Every substantive discussion thread in the session must map to exactly one of:
provenance
the reason (technical failure or user veto)
positions considered, and why it was left unresolved
When unsure whether a discussion was substantive enough to record, include its conclusion — a one-line entry costs little, a lost thread costs the user a re-explanation. Capture the residue of each discussion (what was concluded and why, or why nothing was concluded), never the back-and-forth itself.
handoffs/ if it does not exist: mkdir -p handoffscarryover rule above
handoffs/[YYYY-MM-DD]-[description].mdClassify the session to determine which structural sections are most relevant. If a session spans multiple types, use the primary type and pull in relevant sections from secondary types.
Building new functionality, adding endpoints, creating components.
Key sections: Objective, Implementation State, Architecture/Design Decisions, Files Modified, Remaining Work, Issues Encountered.
Diagnosing and fixing issues, investigating unexpected behaviour.
Key sections: Problem Description, Reproduction Steps, Hypotheses Tested, Root Cause (if found), Fix Applied (if any), Remaining Hypotheses.
Restructuring existing code without changing behaviour.
Key sections: Objective, Refactoring Strategy, What Has Been Refactored, Patterns Being Applied, Files Remaining, Regressions to Watch For.
Environment setup, dependency management, build configuration, tooling.
Key sections: Objective, Configuration Changes Made, What Works Now, What Does Not Work Yet, Environment-Specific Details.
High-level design discussions, structural decisions, API design.
Key sections: Objective, Options Considered, Decisions Made (with rationale), Constraints, Design Artefacts (diagrams, schemas), Open Design Questions.
Writing or fixing tests, improving coverage, test infrastructure.
Key sections: Objective, Test Strategy, Tests Written, Coverage Gaps Remaining, Test Failures Under Investigation.
Sessions spanning multiple types or not fitting neatly into one category.
Key sections: Use the universal structure and pull in type-specific sections as needed.
Assess the complexity of the work to determine how comprehensive the handoff should be. The codebase provides significant context, so the handoff captures what the code cannot: intent, rationale, failed approaches, and session-specific state. Be complete on decisions, rationale, and failed approaches; ruthless on everything else. The coverage rule takes precedence over the word counts: if recording every discussion's residue pushes past a tier's range, that is acceptable — trim narrative, never conclusions.
Simple, focused tasks. One file or a small change, few decisions, clear next steps.
Examples: fixing a straightforward bug, adding a simple utility function, updating a config value.
Moderate tasks touching several files. Meaningful decisions made, some investigation involved.
Examples: implementing a new API endpoint, debugging an intermittent test failure, setting up a new build tool.
Complex work with significant decision-making, multiple files involved, established patterns or conventions being followed.
Examples: implementing a multi-component feature, resolving a complex bug after several failed hypotheses, refactoring a module with many dependents.
Use sparingly. For sessions with extensive investigation, large architectural decisions, or multiple interconnected workstreams.
These word counts are calibration guidelines, not targets to fill.
Every handoff follows this skeleton. Include or exclude sections based on work type and relevance. Do not include empty sections. Reference files by path rather than reproducing content.
# Handoff: [Descriptive Title]
> **Resumption instruction:** Read this handoff, review the listed files,
> then confirm your understanding in 2-3 sentences before proceeding.
> Items marked (user) are user-stated: decisions so marked are fixed and
> must not be revisited without asking; steps so marked must be prompted
> to the user, not attempted.
**Date:** [YYYY-MM-DD]
**Project:** [project path]
**Work type:** [Feature / Bug Fix / Refactoring / Config / Architecture / Testing / Mixed]
**Status:** [In Progress / Paused / Nearing Completion / Blocked]
## Previous Session
<!-- Only if prior handoffs exist -->
- Handoff: `handoffs/[previous-filename].md`
- Live carryover: [restate everything from earlier sessions that is still
relevant — open questions, constraints, conventions. Self-sufficient, not
just a pointer.]
---
## Objective
[What we are trying to accomplish and why. Include enough context that a fresh
session understands both the task and its motivation.]
## Current State
[Precise snapshot of where the work stands. Not a summary of the conversation,
but the actual state. What works, what doesn't, what is partially complete.
Not "we worked on the API" but "the /users endpoint returns 200 with correct
data, the /auth endpoint throws a 401 on valid tokens, investigation ongoing."]
## What Was Done
[Concrete actions taken this session. Focus on outcomes, not conversation
history.]
- [Action] — [outcome or result]
- [Action] — [outcome or result]
## Decisions Made
[Each decision with its rationale AND its origin. Mark decisions that came
from the user — explicit requirements, directions, vetoes, stated opinions —
with **(user)**: these are fixed, and the receiving session must not revisit
them without asking. Unmarked decisions are session choices, revisable with
good reason. The user accepting a Claude proposal counts as unmarked unless
the user added a reason of their own.]
- **(user)** **[Requirement/direction]** — [The user's stated reason, if given]
- **[Decision]** — [Why this was chosen. What alternatives were considered.]
## Approaches That Did Not Work
[Directions explored and rejected. Include what was tried and why it failed
or was abandoned. Distinguish HOW it was rejected: if it failed technically,
give the failure; if the user rejected it, say so and capture their stated
reason — a user veto is not evidence the approach cannot work, and the
receiving session needs to know the difference.]
- **[Approach]** — [Why it did not work]
- **[Approach]** — Rejected by user: [their stated reason]
## Open Discussions
[Topics discussed but not concluded. For each: the topic, the positions or
options considered, and why it was left unresolved (ran out of time, needs
information, user undecided). Without this section, unconcluded threads
vanish and the next session unknowingly starts them from scratch.]
- **[Topic]** — Considered: [positions/options]. Unresolved because: [reason]
## Files Modified
[Files changed during this session, with a brief note on what and why. The
new session can read these files directly.]
- `path/to/file.ext` — [What was changed and the intent]
## Issues / Errors Encountered
[Specific error messages, unexpected behaviours, or blockers. Include exact
error text where relevant — these are hard to rediscover.]
## Open Questions
[Unresolved items needing attention. Frame as specific questions, not vague
areas.]
- [ ] [Specific question]
## Next Steps
[Ordered list of what to do next. The first item is the very next action.
Clear enough that the receiving session knows exactly what to do first. Mark
any step only the user can perform with **(user)** — the receiving session
should prompt for these, not attempt them.]
1. [First action — specific and concrete]
2. **(user)** [Action the user must perform, e.g. reviewing output, merging,
publishing a release]
3. [Third action]
## Possible Directions
[Use INSTEAD of Next Steps when the user has deliberately not chosen what to
work on next. State "Direction undecided" and list the candidate directions as
options with a one-line case for each. The receiving session should present
these as choices, not pick one and proceed.]
- **[Candidate direction]** — [Why it might be next]
## Files to Review on Resume
[Key files the new session should read to get up to speed. Only include files
that are central to understanding the current state of the work.]
- `path/to/file.ext` — [Why this file matters]needs to understand not just the task but why it matters and the scope.
state description, not a narrative. What exists, what works, what is broken, what is incomplete.
is more valuable than the decisions themselves, and the origin determines how the receiving session treats them: user-stated requirements are fixed, session choices are revisable.
Everything the user said about what they want, what is off-limits, and how they want the work done that is not obvious from the code. These carry the (user) marker wherever they appear.
rejection, each with its reason. This prevents the most common failure mode in session handoffs: the new session retrying something already ruled out — or wrongly treating a user veto as a technical impossibility.
decision, a rejected approach, or an open discussion. No thread vanishes.
exactly what to do first without asking. User-only actions marked (user). If direction is genuinely undecided, use Possible Directions instead — do not invent a priority the user never set.
immediately to rebuild context from the code.
full error text when it is central to ongoing debugging.
exact steps to reproduce the problem.
future code should follow (e.g. "all new endpoints use the withAuth middleware wrapper").
was agreed upon but not yet fully implemented.
environment variables that affect the work.
code blocks unless they capture something not obvious from the file itself (e.g. a subtle bug, a specific pattern being followed, a key interface contract).
Claude already knows. "We discussed how middleware works" adds nothing. "Decided to use middleware over route-level auth because [reason]" adds value.
back-and-forth. Not "we discussed whether to use middleware, first considering X, then the user said Y..." but "decided to use middleware because [reason]" — or, if unconcluded, an Open Discussions entry.
output or tool responses.
conclusion and rationale, not every step of the reasoning process.
Before saving the handoff, verify:
user to re-explain anything
rejected approach, or an open discussion — no thread has vanished
requirements, and vetoes carry the (user) marker
failure from user rejection
rather than only linking the previous file
actions marked (user) — or Possible Directions used if direction is undecided
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.