# Session Update

> Synchronize the handoff Board queue. Use after proposing/registering work, after Spectra archive changes Board state, when Remaining/Phase Plan/Related Docs are stale, when the user asks to refresh/update/sync the session board, or when the user asks to correct stale/old handoff Board state. Writes handoff files.

- Skill: `57luo/session-update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 57luo/session-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/57luo/session-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 57Luo (https://skillmd.com/u/57luo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/57luo/session-update

---


# Session Update

Synchronize the living Board queue in the shared handoff file. This skill writes files.

## Artifact Boundary

- Write generated handoff data only under shared project paths, preferably `.session/handoff/` at the main repo/worktree root.
- Never write runtime handoff data inside `.agents/skills/`, `.claude/skills/`, `.codex/skills/`, or another skill installation path.
- If no shared handoff directory exists, create `.session/handoff/`.
- Historical handoffs are read-only. Record corrections in today's handoff rather than editing older daily files.

## Handoff Root Resolution

Follow `## Handoff Root Resolution` in `session-handoff/schema/handoff.md`. As a writer skill: refuse to write a divergent worktree-local handoff directory and report it as a migration/mismatch warning.

## Core Rules

- Read project instructions when present: `AGENTS.md`, `CLAUDE.md`. Do not read `.claude/settings.json` by default; inspect it only under the `Project Instruction Reading Boundary` in `session-handoff/schema/handoff.md`.
- Use `.session/handoff/YYYY-MM-DD.md` for today's Board. If today's file does not exist, create it from the most recent handoff following the inheritance rules in `## Artifact Boundary` of `session-handoff/schema/handoff.md`.
- Do not update `## Active Work`; claiming belongs to `session-claim`, completion belongs to `session-handoff`.
- `session-update` is not a required pre-step for `session-handoff`. Use
  `session-handoff` to close/pause a task and perform Handoff Board Sync for that
  task; use `session-update` for broader queue grooming and stale Board cleanup.
- Do not use this skill for handoff completion records; use `session-handoff` when a session entry is needed.
- Keep `## Remaining` for claimable unfinished work only.
- Treat `## Remaining` as the claimable queue. In Spectra projects, put parked
  or active Spectra changes that can be claimed as future work in `Remaining`;
  the next session still follows the Spectra workflow appropriate to that
  change's state.
- Treat `## Phase Plan` as ordering/dependency/phase context. Do not use it as a
  historical checklist, and do not duplicate the complete `Remaining` queue in
  `Phase Plan`.
- Remove completed/archived items from `Phase Plan` unless they are mentioned
  only as brief dependency context for current work. Historical completion
  belongs in Session Log, Spectra archive, and `## Spectra` recent archive.
- Do not duplicate claimed work across `Active Work` and `Remaining`.
- Active Work checks here are read-only. If same workspace/branch has multiple
  different `in-progress` work items, a row has missing workspace/branch, or a
  claimable Remaining item is already active/paused, report a Board mismatch and
  direct the user to `session-claim` or `session-handoff`; do not rewrite Active Work.
- Do not invent progress-source paths. Mark source-less items as `Progress Source: Handoff only`.
- Before writing, verify actionable Board entries against current sources when available.

## Concurrent Write Guard

Follow `## Concurrent Write Guard` in `session-handoff/schema/handoff.md` — prefer the `session-handoff/scripts/locked_write.py` helper over manual lock steps. Apply the guard to `Phase Plan`, `Remaining`, `Related Docs`, `Open Questions`, `Blockers`, and `Spectra` (`session-update` does not write `Active Work`).

## Quote-Trace Discipline

Follow `## Quote-Trace Discipline` in `session-handoff/schema/handoff.md`.

## Claim Board Scope

- If Spectra is detected by CLI or `openspec/`, `Active Work`, `Remaining`, and `Phase Plan` should track Spectra change names only.
- In Spectra projects, do not register ad-hoc/non-Spectra work as claimable Board work. Preserve displaced context only in `Open Questions`, `Blockers`, `Related Docs`, or Board notes with source labels; tell the user to run `session-handoff` if a retrospective log entry is needed.
- In Spectra projects, move existing non-Spectra `Remaining` entries out of the claimable queue during update: preserve them as `Open Questions`, `Blockers`, `Related Docs` context, or Board notes with source labels.
- If Spectra is absent, non-Spectra work may be registered as claimable work when it has a stable slug/name and either a progress source or explicit handoff-only completion criteria.

## Spectra Discovery

Spectra is optional, but detection is required. Follow `## Spectra Discovery`
in `session-handoff/schema/handoff.md` (including the `session-update` delta
there).

## Workflow

1. Read today's shared handoff file, or create it from the most recent unfinished Board per the schema's inheritance rules (`## Artifact Boundary`).
2. Discover work items from:
   - existing Board
   - progress-source docs referenced by Board
   - user-provided work item names
   - Spectra active/parked changes
3. Re-read current sources that determine completion, blockers, dependencies, or
   durable documentation sync checks that belong in Related Docs.
4. Inspect `## Active Work` read-only for occupancy/stale/duplicate-Remaining mismatches using the `Workspace`/`Branch` schema. Report mismatches; do not edit Active Work.
5. Update:
   - `## Phase Plan`: phase/dependency/order notes only; not a changelog and not
     a duplicate claim queue
   - `## Remaining`: claimable unfinished work only
   - `## Related Docs`: durable documentation sync checks for claimed work,
     preserving `triggers:` notes when present and enforcing
     `Related Docs Scope` from the shared schema
   - `## Open Questions`: unresolved questions only
   - `## Blockers`: active blockers only
   - `## Spectra`: only when Spectra is detected
6. Preserve explicit paths and user notes unless current sources clearly supersede them.
7. Audit `Related Docs` trigger notes against git status/diff and current Board
   items. Surface missing or stale triggers, and groom out source/test/generated
   paths that violate the shared schema.
8. Report what changed and which sources were checked.

## Board vs Log Boundary

Follow `## Board Semantics` in `session-handoff/schema/handoff.md` for the
Board-vs-Session-Log layering and the rule that resolved/stale notes are removed
from the Board. `session-update` grooming-specific actions:

- Baseline dirty file blocks at the Board top: collapse to one-line summary
  (`Session N baseline: X modified + Y untracked; see Session N Notes`).
  Move displaced detail into a note inside the relevant Session Log entry; do
  not silently drop it.
- When removing stale Board notes (resolved conflict warnings,
  `(inherited from...)` labels on sections already touched today, occupancy
  notes that no longer apply), capture historically useful context as a
  date-labelled Board note or fold it into a Session Log entry if it explains a
  past decision.

## Open Questions Prune

`session-update` owns the interactive Open Questions prune. Staleness and the
exemption rule are defined in `## Open Questions and Ideas Backlog` in
`session-handoff/schema/handoff.md`; `session-handoff` only surfaces stale
questions as `prune candidate` and defers the prune to here.

For each detected stale, non-exempt question, prompt the user with three
options:

- **Move to ideas backlog** — invoke the `project-logbook` skill (via the
  Skill tool) with `--backlog add` to record it in
  `.knowledge/ideas-backlog.md`. Never edit that file directly from this
  skill — writes must go through project-logbook's insert script, which
  validates the schema and rebuilds `_backlog_index.json`. Preserve
  `flagged: YYYY-MM-DD` and `last-seen: YYYY-MM-DD` metadata.
- **Delete** — remove from Open Questions.
- **Keep** — leave in Open Questions (resets the 14-day clock via
  `last-seen` update).

## Related Docs Freshness

Follow `## Related Docs Freshness` and `## Related Docs Scope` in
`session-handoff/schema/handoff.md` for `last reviewed` stamping, the 30-day
stale flag, and what may appear in `## Related Docs`. `session-update`
specifics:

- Do not list parked Spectra change directories in `Related Docs` merely
  because those changes are queued in `Remaining`; the queued change name is
  the Board pointer. Add a parked proposal/design/spec artifact only when this
  update actually changed or must synchronize that artifact's content.
- Do not list archived Spectra directories in `Related Docs` as history; keep
  only the latest one or two relevant archives in `## Spectra` Recent archive.

## Spectra Section Scope

Follow `## Spectra Board Scope` in `session-handoff/schema/handoff.md` for what
`## Spectra`, `## Remaining`, and `## Phase Plan` should contain: active changes
listed in full, only relevant parked changes plus
`parked total: N (see spectra list --parked)`, and recent archives limited to
the latest one or two relevant to current work. No `session-update`-specific
additions.

## Non-Spectra Registration

Only when Spectra is absent:

- If the user provides a work item name, add it to `Remaining`.
- If a progress source is provided or obvious, link it.
- If no progress source is available, require a stable slug/name and explicit handoff-only completion criteria; mark `Progress Source: Handoff only`.
- Use generic groupings such as `Unphased` or the user's supplied grouping when no phase plan exists.

## Output

Summarize:

- Board file written
- Remaining/Phase Plan/Related Docs changes
- Open Questions/Blockers changes
- Spectra result, if relevant
- Sources checked
- Items still `handoff-only`
- Active Work mismatches found read-only, if any