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 .claude/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 .claude/handoffs/, suggest to the user that older ones be archived or deleted — superseded handoffs add noise when listing and resuming.
.claude/handoffs/ if it does not exist: mkdir -p .claude/handoffscarryover rule above
.claude/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.
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.
**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: `.claude/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. The rationale prevents the new session from
relitigating settled questions. Without the "why", the new session may
unknowingly reverse a carefully considered choice.]
- **[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. This is one of the highest-value sections — it prevents the
most common failure mode: the new session repeating work that has already been
tried and rejected.]
- **[Approach]** — [Why it did not work]
## 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.]
1. [First action — specific and concrete]
2. [Second action]
3. [Third action]
## 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.
valuable than the decisions themselves. Without rationale, the new session may unknowingly reverse a carefully considered choice.
the most common failure mode in session handoffs: the new session retrying something that has already been tried and ruled out.
exactly what to do first without asking.
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.
want the work done that are not obvious from the code.
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.
whether to use middleware" but "decided to use middleware because [reason]."
output or tool responses.
conclusion and rationale, not every step of the reasoning process.
Before saving the handoff, verify:
user to re-explain anything
rather than only linking the previous file
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.