--- name: session description: Session start, closeout and handoff. Use when starting, switching topic, closing, handing off or a second human joins. Not for parallelism (skill parallelize). argument-hint: "[start | review | handoff | audit]" triggers: - user - model allowed-tools: - read - grep - glob - exec - edit --- # Session One skill, four modes: `start` opens and scopes the session, `review` closes it with evidence, `handoff ` writes the continuation record, `audit` reviews many sessions at once. ## start - Resolve the project profile first (`references/project-profile.md`): `project` and `stacks`; every kit skill resolves it the same way at its first step and runs the kit tools by the names its § 3 gives. - When the outcome sentence (`AGENTS.md` § Session) cannot be written, ask before proceeding. - When `AGENTS.md` § Work loop calls for a plan, propose planning mode before editing; once a plan is approved, execute it without reopening it. - Before the first edit in a worktree or folder that a state or handoff file describes, read that file's top line `Writer: since `. A line naming another session that is still running means stop and ask the user; never write beside it. Otherwise add the line before the first edit and remove it at close or handoff. - Keep follow-ups, and each decision or correction with its reason when it settles, in the issue, PR or handoff record, not conversational memory. - Owner-review autonomy (`AGENTS.md` § Boundaries): write the record before the act, where the owner will look: a PR comment for an act on a PR (label, merge, `Files` widening), the session's STATE file for a host, config or session act, and one `OWNER-TODO.md` line for what the owner must check or undo. The record names the act, the reason, the evidence (head SHA, command and result) and the way back. Before an act that cannot be undone (a deletion, a history rewrite, an applied migration), keep a way back first: a dated backup, a tag or a branch. At batch end or close, list every such act in one "decisions to review" section; a wrong act becomes a fix or revert PR, never a silent undo. - Exhausted-session signals: rereading already-read files, compressed context, an outcome already delivered, new unrelated requests, or roughly two hours of work. Suggest the handoff mode and a new session; continue only if the user chooses to. - A second human joins the backlog: apply the condition → action rules in `references/two-humans.md`. - Match the agent tier: suggest a smaller tier for a mechanical one- or two-file task with no decision or investigation; keep the current tier for architecture, investigation or risk. - Close explicitly: run the review mode for the evidence summary and optional kit proposal; when work is pending or transferring to another agent, point to the issue or PR that records its state, and run the handoff mode only when none does. ## review - Re-read the actual diff, commands and outputs; do not reconstruct them from memory. Report in at most six technical lines: done with paths and verification, unverified claims, and one concrete next step. - If work is committed or pending, point the summary to the issue or PR that records its state; run the handoff mode first only when no such record exists. Cite the proof already recorded; re-run nothing just to restate it. - List the worktrees this session created (`git worktree list`): remove only those whose branch is merged and whose tree is clean; report each one with uncommitted work and its dirty paths, and never remove it. - In Devin Cloud, open Session insights for ACU size, issues and the improved prompt; treat "misleading guidance" as a skill-description defect. - Look for a demonstrated kit gap, or a rule or step that cost time without changing the outcome, using the signal table in `references/kit-proposal.md`, then decide: no observed signal → stop after the summary; project-only discovery (critical constant, fragile convention) → propose one line for that repo's `AGENTS.md` on the spot, shaped `when , do , because `; several signals → choose the strongest and put the rest in the handoff as follow-ups. Never propose kit growth because it merely sounds useful. - Propose with the exact block in `references/kit-proposal.md`, which also holds what to ask and how accepted work closes. ## handoff - Use `../../templates/doc-session-handoff.md`; the record must let a new session continue without this conversation. - Save to the project-defined location or `docs/sessions/YYYY-MM-DD-topic.md`. Link specs, decisions, commits and reports instead of copying them. - Before writing, run `references/handoff-record.md`: collect the observed state, name exactly one executable first task, and confirm completeness before closing. ## audit - Read and follow `references/cross-session-audit.md`. The input is the redacted extract of `AUDIT` (`references/project-profile.md` § 3), never a raw transcript. - Classify memory entries and recurring failures, re-check every claim before the report, and sort actions by the number of sessions that cite them. - It only proposes, with one exception: expired one-night, one-batch or one-session memory entries older than 7 days move to `memory/archive/`. Every other memory change, a repository `AGENTS.md` promotion (a PR) and a kit promotion (a `Kit [PROPOSAL]` block) waits for the user's yes. ## Rules - The handoff record is written only when invoked as session handoff , or when the user asks for a handoff in words; a model-triggered load runs start or review and may only suggest handoff. - Do not edit the kit in the same turn as the proposal. - A dirty tree is a blocker: list every path. - The audit mode runs only when invoked as `session audit`, by the weekly scheduled task, or when the user asks for the cross-session audit in words. Done when: one outcome stayed in scope, the review delivered verified status with unverified items and one next step, and any requested handoff record names one unambiguous first action.