resume-session — tactical-first session entry
Self-validate after edits. Any change to this skill's files (SKILL.md, scripts/, references/, templates/, assets/) must be followed by ./scripts/validate.sh from the skill directory. Hard findings → create-skill Optimize lane.
This skill exists to surface the most recent tactical checkpoint before doing broader repo discovery. It is a thin recovery layer, not a replacement for normal AGENTS, workflow, or validation loading.
Operating contract
| Field |
Decision |
| Primary archetype |
deterministic script workflow |
| Secondary archetypes |
reference workflow |
| Operator trigger |
/resume-session, resume session, continue where I left off, pick up where we left off |
| Output |
the contents of canonical .session/CURRENT.md plus restored goal state and a concise tactical synthesis |
| Success evidence |
inspector classifies checkpoint eligibility; only a fresh, consistent explicit goal is matched or created without replacing another unfinished goal |
| Deterministic surface |
the global shell command resume-session |
| Judgment surface |
deciding how much of the checkpoint is still relevant before acting |
| Context loading |
read checkpoint first, then continue with normal repo/workflow loading |
Main flow
Preflight
- Honor
RESUME_SESSION_ROOT, then search the current directory and its
ancestors for the checkpoint. Only then use git rev-parse; never let a
home-directory Git root displace a nested workspace checkpoint.
- Look for
.session/CURRENT.md. Use legacy .claude/session-data/CURRENT.md only before the canonical workspace exists.
- Run
resume-session --inspect-json. Its inspector is the sole owner of checkpoint freshness and consistency.
- Treat
ensure-active as a candidate, not permanent authority. Automatic restoration requires eligibility: fresh; review-checkpoint requires current owner-plan and repo evidence before selecting any goal.
- A
reference-only, missing, invalid, expired, future-dated, wrong-root, branch-diverged, commit-diverged, route-invalid, or chain-conflicting checkpoint must not auto-create a goal.
Do
resume-session --inspect-json
resume-session
If the file exists, synthesize a short From prior session block with:
- where work left off
- saved Codex goal state, when explicitly present
- next action
- route owner, first command, and stop condition, if a
route_contract is present
- blockers, if any
- notable learnings, if any
Before running any saved route command, restore only when the inspector returns
mode: resume-exact-goal:
- Call
get_goal.
- If the current task already has the same unfinished objective, reuse it.
- If the current task has no unfinished goal, call
create_goal with the exact
saved objective. Do not infer or shorten its completion criteria.
- If a different unfinished goal exists, do not replace it. Report the
conflict and wait for operator direction.
- For
mode: choose-next-goal, use the current owner plan instead of the checkpoint.
- For
mode: review-checkpoint, treat the saved objective as evidence only. Verify it against current owner and repo state; if still current, select it through the normal new-goal path rather than silently restoring it.
Goal restoration does not authorize resuming provider calls, deployment,
external sends, destructive actions, or any other gated saved next action.
If route_contract.first_command is present, verify it is still plausible for the current repo and run or inspect that command before broad workflow discovery. Otherwise continue with the repo’s normal retrieval path: AGENTS, workflow docs, validation docs, and current file state.
Closeout
- If the checkpoint is missing, say so plainly and fall back to normal repo discovery.
- If the checkpoint is clearly stale or contradicted by the current repo state, call that out before continuing.
- Do not auto-execute the saved next action without checking current repo evidence.
- Do not mark a restored goal complete merely because the checkpoint was read;
completion still requires the saved stop condition to be satisfied.
Friction introspection
| Friction source |
Action |
| Missing checkpoint |
Fall back cleanly; do not invent prior context |
| Checkpoint stale or misleading |
Do not create its goal; prefer current owner/repo evidence and write a fresh checkpoint only after current intent is established |
| Checkpoint has known route fields |
Use the saved first command as the narrowest starting point before broad retrieval |
| Explicit saved goal is absent in the current task |
Create the exact saved objective before running the saved route |
| A different unfinished goal already exists |
Preserve it, report the conflict, and do not replace it automatically |
| Read path broken |
Fix the global wrapper in ~/.local/bin/ and keep this skill aligned |
Hard rules
- Read first, verify second. Use the checkpoint as a starting point, not as truth over the repo.
- No repository writes. Inspection is read-only except for an optional private temporary exact-goal file used by orchestration.
- Be honest about staleness. If the checkpoint conflicts with the repo, say so.
- Keep retrieval layered. Tactical checkpoint first, then normal project context.
- Known route before generic retrieval. A saved first command is a routing hint, not truth, but it should be checked before loading broad docs.
- Explicit goals only. Restore the exact checkpointed objective; never
manufacture a goal from ordinary
working_on or next_action prose.
- Never replace unfinished work silently. A different unfinished goal is
a blocking conflict that requires operator direction.
- Freshness is deterministic. Do not override inspector rejection merely because the operator opened a fresh task or invoked orchestration.
Cross-references
- scripts/validate.sh — audit wrapper for this skill
- scripts/resume-session — source of truth for the installed wrapper
- scripts/inspect_checkpoint.py — freshness, repo-consistency, route, and exact-goal classifier
- scripts/test_checkpoint_inspector.py — positive and negative eligibility cases
- scripts/test_resume_session.sh — deterministic root-resolution test
~/.local/bin/resume-session — deterministic read implementation- sibling skill:
save-session
Why this skill exists
This prevents the first few minutes of a resumed session from being wasted on reconstructing tactical intent from git status and filenames alone. A quick checkpoint read makes the next agent faster without pretending it replaces normal validation and repo discovery.
1---2name: resume-session3description: Inspect `.session/CURRENT.md`, surface the tactical handoff, and restore only an eligible explicit Codex goal. Triggers: `/resume-session`, `resume session`, `continue where I left off`, `pick up where we left off`. Use when a prior session may contain useful intent, but first reject stale, malformed, branch-diverged, commit-diverged, route-invalid, or reference-only checkpoints. Read legacy `.claude/session-data/CURRENT.md` only before `.session/` exists.4---56# resume-session — tactical-first session entry78> **Self-validate after edits.** Any change to this skill's files (SKILL.md, scripts/, references/, templates/, assets/) must be followed by `./scripts/validate.sh` from the skill directory. Hard findings → create-skill Optimize lane.910This skill exists to surface the most recent tactical checkpoint before doing broader repo discovery. It is a thin recovery layer, not a replacement for normal AGENTS, workflow, or validation loading.1112## Operating contract1314| Field | Decision |15|---|---|16| Primary archetype | deterministic script workflow |17| Secondary archetypes | reference workflow |18| Operator trigger | `/resume-session`, `resume session`, `continue where I left off`, `pick up where we left off` |19| Output | the contents of canonical `.session/CURRENT.md` plus restored goal state and a concise tactical synthesis |20| Success evidence | inspector classifies checkpoint eligibility; only a fresh, consistent explicit goal is matched or created without replacing another unfinished goal |21| Deterministic surface | the global shell command `resume-session` |22| Judgment surface | deciding how much of the checkpoint is still relevant before acting |23| Context loading | read checkpoint first, then continue with normal repo/workflow loading |2425## Main flow2627### Preflight28291. Honor `RESUME_SESSION_ROOT`, then search the current directory and its30 ancestors for the checkpoint. Only then use `git rev-parse`; never let a31 home-directory Git root displace a nested workspace checkpoint.322. Look for `.session/CURRENT.md`. Use legacy `.claude/session-data/CURRENT.md` only before the canonical workspace exists.333. Run `resume-session --inspect-json`. Its inspector is the sole owner of checkpoint freshness and consistency.344. Treat `ensure-active` as a candidate, not permanent authority. Automatic restoration requires `eligibility: fresh`; `review-checkpoint` requires current owner-plan and repo evidence before selecting any goal.355. A `reference-only`, missing, invalid, expired, future-dated, wrong-root, branch-diverged, commit-diverged, route-invalid, or chain-conflicting checkpoint must not auto-create a goal.3637### Do3839```bash40resume-session --inspect-json41resume-session42```4344If the file exists, synthesize a short `From prior session` block with:4546- where work left off47- saved Codex goal state, when explicitly present48- next action49- route owner, first command, and stop condition, if a `route_contract` is present50- blockers, if any51- notable learnings, if any5253Before running any saved route command, restore only when the inspector returns54`mode: resume-exact-goal`:55561. Call `get_goal`.572. If the current task already has the same unfinished objective, reuse it.583. If the current task has no unfinished goal, call `create_goal` with the exact59 saved objective. Do not infer or shorten its completion criteria.604. If a different unfinished goal exists, do not replace it. Report the61 conflict and wait for operator direction.625. For `mode: choose-next-goal`, use the current owner plan instead of the checkpoint.636. For `mode: review-checkpoint`, treat the saved objective as evidence only. Verify it against current owner and repo state; if still current, select it through the normal new-goal path rather than silently restoring it.6465Goal restoration does not authorize resuming provider calls, deployment,66external sends, destructive actions, or any other gated saved next action.6768If `route_contract.first_command` is present, verify it is still plausible for the current repo and run or inspect that command before broad workflow discovery. Otherwise continue with the repo’s normal retrieval path: AGENTS, workflow docs, validation docs, and current file state.6970### Closeout71721. If the checkpoint is missing, say so plainly and fall back to normal repo discovery.732. If the checkpoint is clearly stale or contradicted by the current repo state, call that out before continuing.743. Do not auto-execute the saved next action without checking current repo evidence.754. Do not mark a restored goal complete merely because the checkpoint was read;76 completion still requires the saved stop condition to be satisfied.7778#### Friction introspection7980| Friction source | Action |81|---|---|82| Missing checkpoint | Fall back cleanly; do not invent prior context |83| Checkpoint stale or misleading | Do not create its goal; prefer current owner/repo evidence and write a fresh checkpoint only after current intent is established |84| Checkpoint has known route fields | Use the saved first command as the narrowest starting point before broad retrieval |85| Explicit saved goal is absent in the current task | Create the exact saved objective before running the saved route |86| A different unfinished goal already exists | Preserve it, report the conflict, and do not replace it automatically |87| Read path broken | Fix the global wrapper in `~/.local/bin/` and keep this skill aligned |8889## Hard rules90911. **Read first, verify second.** Use the checkpoint as a starting point, not as truth over the repo.922. **No repository writes.** Inspection is read-only except for an optional private temporary exact-goal file used by orchestration.933. **Be honest about staleness.** If the checkpoint conflicts with the repo, say so.944. **Keep retrieval layered.** Tactical checkpoint first, then normal project context.955. **Known route before generic retrieval.** A saved first command is a routing hint, not truth, but it should be checked before loading broad docs.966. **Explicit goals only.** Restore the exact checkpointed objective; never97 manufacture a goal from ordinary `working_on` or `next_action` prose.987. **Never replace unfinished work silently.** A different unfinished goal is99 a blocking conflict that requires operator direction.1008. **Freshness is deterministic.** Do not override inspector rejection merely because the operator opened a fresh task or invoked orchestration.101102## Cross-references103104- [scripts/validate.sh](scripts/validate.sh) — audit wrapper for this skill105- [scripts/resume-session](scripts/resume-session) — source of truth for the installed wrapper106- [scripts/inspect_checkpoint.py](scripts/inspect_checkpoint.py) — freshness, repo-consistency, route, and exact-goal classifier107- [scripts/test_checkpoint_inspector.py](scripts/test_checkpoint_inspector.py) — positive and negative eligibility cases108- [scripts/test_resume_session.sh](scripts/test_resume_session.sh) — deterministic root-resolution test109- `~/.local/bin/resume-session` — deterministic read implementation110- sibling skill: `save-session`111112## Why this skill exists113114This prevents the first few minutes of a resumed session from being wasted on reconstructing tactical intent from git status and filenames alone. A quick checkpoint read makes the next agent faster without pretending it replaces normal validation and repo discovery.
ingpoc