session-close

Purpose

This skill bundles all end-of-session housekeeping into a single invocation. Without it, the user must manually instruct PM updates, workflow document updates, commits, and session capture — a sequence that is the same every time and easy to skip or partially complete.

Preconditions

• A work session is ending (the user says "close", "wrap up", "session-close", or similar).
• The agent has context about what was done during the session.

Required Reads

1. .agents/state/active-workflows.md — identify which workflow(s) were touched.
2. .agents/pm/pm-index.md — know which PM units exist.
3. If a workflow was active: the workflow's handoff.md and run-log.md.

Procedure

1. Update workflow documents. For each workflow touched during this session: a. Ensure run-log.md has entries covering all meaningful work done this session. If the last run-log entry is stale (does not cover recent work), append a catch-up entry. b. Update handoff.md with current status, the next exact step, and any new risks or blockers discovered. c. If the workflow is complete (all acceptance criteria met), run the workflow-complete procedure (see .agents/skills/workflow-complete/SKILL.md).

2. Update Project Memory. Run the pm-update procedure: a. Filter for durable knowledge learned this session. b. Update affected PM units (including code-navigation units if source files changed). c. Update pm-current-state.md with any changed work areas, risks, or workflow states. d. Record any decisions made to pm-decisions.md. e. Record any new terminology to pm-glossary.md. f. Update pm-index.md if units were created or changed.

3. Update state files. Ensure current-focus.md and active-workflows.md reflect the current project state. If a workflow completed, apply the archival steps from workflow-complete.

4. Commit changes in logical groups. Stage and commit changes with clear, descriptive messages. Group logically:

   • Source code changes: one or more commits covering the implementation work.
   • Workflow document updates (run-log, handoff, dossier state changes): one commit.
   • PM updates: one commit.
   • State file updates: may be combined with workflow or PM commit if small.

   Use conventional commit messages that reference the workflow ID where applicable (e.g., "ft_feature-name: implement phase 2 acceptance criteria"). Do not force-push or amend prior commits.

   Skip/caution rules:

   • If the worktree contains staged or unstaged changes unrelated to the current session's work, do not bundle them. Commit only changes the agent made or can confidently attribute to this session.
   • If logical commit boundaries are unclear (e.g., a large refactor with interleaved source and test changes), ask the user how they want commits grouped rather than guessing.
   • If the user has not indicated that commits are desired in this session's context, skip the commit step and note: "Uncommitted changes remain. Commit when ready or run /session-close again after review."
   • Never force-push or amend prior commits during session-close.

5. Run session-capture. Follow the session-capture procedure (see .agents/skills/session-capture/SKILL.md) to create a normalized session record. This includes the review cadence check — if enough captures have accumulated, the capture will recommend running /session-review.

6. Deliver summary. Report to the user:

   • What was committed (brief list of commit messages).
   • Workflow state changes (any completions, new blockers).
   • PM updates made (units touched, decisions recorded).
   • Whether a session review is recommended.
   • The session capture file path.

7. Remove session-active marker. Delete .agents/state/session-active.md. This signals to the next /session-init that this session closed properly. This is the last action in the close sequence.

Output

No single output file. This skill orchestrates updates across multiple files:

• Workflow run-log.md and handoff.md (and dossier.md if completing).
• PM files (pm-current-state.md, units, pm-decisions.md, pm-glossary.md, pm-index.md).
• State files (current-focus.md, active-workflows.md).
• Git commits.
• Session capture file at .untracked/session-captures/<timestamp>-<agent>.md.

Completion Criteria

• All active workflow documents are up to date (run-log, handoff).
• PM has been updated with any durable knowledge from this session.
• State files reflect current project state.
• All changes are committed with descriptive messages.
• A session capture file has been written.
• The user has received a summary of what was done.

Error Handling

• If no meaningful work was done this session (nothing to commit, no state changes), still produce a minimal session capture noting "No significant work this session" and skip the commit step.
• If a commit fails (e.g., pre-commit hook), report the failure and the error message. Do not skip the remaining steps — continue with session capture even if commits fail.
• If PM update encounters missing index or units, note the inconsistency in the session capture and recommend running /pm-validate next session.
• If the user interrupts mid-close (e.g., wants to do more work), stop the close sequence and resume normal operation. The user can re-run /session-close later.