Session Status

---
name: session-status
description: "Analyzes current session state, no cleanup. Full mode (default): plan+TaskList+history scan, emits a next-session prompt. Mid mode (`/session-status mid`): fast 'done vs remaining' snapshot. Repo/PR state is optional; both modes run outside a repo."
---

# Session and Repository Status Analysis

This skill provides a read-only snapshot of the current session's progress,
remaining work, encountered issues, and repository state. It does not
perform any repository cleanup (like deleting branches or worktrees)
or wrap up the session.

> **State warning**: Branch state, remote tracking, TaskList contents, and plan
> checklist state all change between invocations. Re-run every git/gh command
> and re-call `TaskList` from Step 1; never trust prior outputs from this
> conversation.

## Two modes

| Invocation | Mode | Use |
| --- | --- | --- |
| `/session-status` (default) | **Full** — Steps 1–5, the dashboard + next-session prompt | end of session, wrap-up, deciding what to hand off |
| `/session-status mid` | **Mid-session** — the quick check below | mid-flight "where am I: what's done, what's left" |

Both modes re-derive live state; neither performs cleanup. Mid-session mode is a
fast orientation snapshot — it skips the conversation-history scan (Step 2), the
triage (Step 4), and the next-session prompt (Step 5). Reach for it when you just
want to see progress, not plan a handoff.

## Mid-session mode

Do only this, then stop:

1. Resolve the plan file (Step 1a) and read its open checklist items with line
   numbers. Call `TaskList`.
2. If — and only if — the cwd is a repository, run `git status -sb` and note
   branch and ahead/behind:

   ```bash
   git rev-parse --is-inside-work-tree >/dev/null 2>&1
   ```

   When that fails, omit the `Branch:` line entirely. Do not print an error and
   do not print a placeholder.
3. Count done vs remaining across both the plan checklist and `TaskList`.
4. Print the compact snapshot — **plain language, no dashboard**:

```text
Mid-session: <n> done / <m> left
  Just finished:  <most recent completed item, in human terms>
  Now / next:     <the in_progress item, or the next open one>
  Still open:     <short list of remaining items, plan line #s or task IDs>
  Branch:         <name> (<ahead/behind/clean>)     ← omit if not a repository
```

State remaining work in the user's terms ("the org-admin token still needs
scoping"), not internal labels ("task #7 pending"). If the plan is complete, say
so in one line and suggest `/wrap-up`. Do not emit a next-session prompt in this
mode — that is what full mode and `/handoff` are for.

---

## Full mode

## Step 1: Determine Plan and TaskList State

Determine the status of the current session's plan, checkboxes, and task
harness.

### 1a. Resolve which plan file belongs to this session

When a session enters plan mode, the harness injects a `<system-reminder>` into
the conversation containing a literal `## Plan File Info:` block that names the
plan file's absolute path (shape: `<HOME>/.claude/plans/<slug>.md`).

To resolve:

1. Scan the current conversation context for `<system-reminder>` blocks whose
   body contains a path matching the regex
   `[^[:space:]]+/\.claude/plans/[^[:space:]]+\.md`.
2. If multiple matches exist, take the **most recently quoted** one — latest
   in conversation order.
3. If zero matches exist, this session never entered plan mode. Treat the
   plan checklist as empty.

### 1b. Read the resolved plan file

If 1a returned a path, read that file. Extract:

- GitHub-style checkboxes (`- [ ]` / `- [x]`) with their line numbers.
- Numbered or bulleted step lists under headings such as "Step", "Phase",
  "Tasks", or "Files to Change", but only when an item has an unambiguous
  done/not-done signal in the file itself or in this session's conversation.

### 1c. Read the harness TaskList

Call `TaskList` and inspect `status` per task.

### 1d. Conversation evidence for ambiguous items

For checklist items without an explicit `[x]`, decide based on this session's
actual evidence: file edits, command output, and test results visible in this
conversation. Be conservative: if in doubt, treat as incomplete. Never consult
history from other sessions.

### Completion rule

The plan is complete iff:

- every `TaskList` task has `status == "completed"` (or the list is empty), AND
- every plan-file checklist item is checked or has clear conversation evidence
  of completion (or there is no plan file at all).

---

## Step 2: Gather Unfinished Work and Session Issues

Scan the conversation history in **reverse chronological order**, stopping when
no new items appear for ~10 consecutive messages.

### 2a. Gather Unfinished Work

- **Incomplete tasks** — anything started but not finished, or marked as
  TODO/FIXME during this session.
- **Items needing production-readiness** — code that works but needs hardening,
  tests, error handling, or documentation before it is production-ready.
- **Future work identified** — any issues, improvements, or ideas called out
  during the session as "later", "follow-up", "out of scope", or similar.

### 2b. Gather Session Issues

- Errors (build failures, test failures, runtime errors).
- Warnings (linter warnings, deprecation notices, compiler warnings).
- Flaky or unreliable behavior observed.
- Workarounds applied that should be properly fixed.
- Tool or dependency issues encountered.

---

## Step 3: Analyze Repository & Git Status (only in a repository)

Gate the whole step:

```bash
git rev-parse --is-inside-work-tree >/dev/null 2>&1
```

If it fails, skip Step 3 entirely, render the `Git & Repository Status:` block as
`not a repository — skipped`, and continue to Step 4. Plan and task state are
what this skill is really reporting; version control is enrichment.

When it succeeds, perform git and GitHub checks to locate active changes and
remote state:

1. Run `git status` to identify modified/untracked files and the current branch
   name.
2. Determine if the current branch has unpushed commits or is out of sync with
   its remote tracking branch.
3. Identify open PRs or issues associated with the current branch or project
   using `gh pr list --state open --json number,title,url,headRefName`. Match by
   branch name `headRefName` to find the PR for the current branch.
4. Capture full URLs for any PR or issue referenced (e.g.,
   `https://github.com/<owner>/<repo>/pull/<n>`), never bare numbers.
   Always emit the full URL on first reference. Bare #123 or PR 123
   references are forbidden. If the same number appears again in the
   same block, a bare #123 is acceptable as a short reference after the
   URL has been shown once.
5. **Validation follow-up** (refs dryvist/ai-assistant-instructions#749): for
   every open PR this session authored, check the `agent-validated` commit
   status on the current head SHA and flag as needs-follow-up if missing,
   stale, or `failure`. Exact command and flag conditions:
   [references/output-format.md](references/output-format.md#validation-follow-up-check).

---

## Step 3.5: Delegate the bulk read

Steps 2 and 3 are the token-heavy, reasoning-light half of this skill: the
reverse-chronological conversation scan for unfinished work and pivots, the
plan-file checkbox extraction, and the `git status` / `gh pr list` / commit-status
tables. Hand that raw material to the **router** via the `local-subagents`
skill (ai-delegation) at the cheapest capable tier — alias `cheap`, or a subagent
carrying an explicit lower `model:` when the conversation exceeds one call's
capacity. The premium lead triages (Step 4) over the returned table, not the dump.

Cap the input: the plan file, at most 30 open PRs, and the history scan's own
stop rule (~10 quiet messages). Truncate rather than paginate. Exact
small-model prompt text:
[references/output-format.md](references/output-format.md#small-model-extraction-prompt-step-35).

**Fallback (verbatim from `local-subagents`)**: none of the router's failure
paths authorize a silent fallback. "Absorbing the work back into your own
context without saying so is the exact cost delegation was meant to avoid, and
it hides the failure from whoever pays for it." If the router is unreachable, do
the step yourself and **say so in the Step 5 dashboard**. Never silently skip it.

## Step 4: Triage and Recommendations

Split the gathered items into three buckets:

1. **Next-session prompt** — items small enough to complete in a single focused
   session (roughly 1–3 tasks). Combine related items where possible.
2. **Tracker items** — code, config, or repo defects and features, plus chores,
   tech debt, and side quests: something has to change and it will not happen
   this session. These go to the issue tracker, **never to GitHub Issues**.
3. **Incident tickets** — operational/incident-shaped items: a production or
   infrastructure anomaly, an RCA- or postmortem-worthy event, a security
   finding, or something a runbook should have caught. The incident system of
   record owns these; they never become tracker items alone and never appear in
   a public repository.

An item that is both (e.g. a bug that caused an outage) gets split: an incident
ticket for the outage, a tracker item for the underlying code fix, each
referencing the other's URL.

**Triage only — this skill does not create anything.** Routing details,
dedup-before-create, and actual item creation belong to the `track-followups`
skill (this plugin), which `/wrap-up` invokes at Path A step A2.5. Duplicating
those mechanics here is how the two drift apart.

---

## Step 5: Output Format

Goal: present a live, human-facing dashboard covering plan status, TaskList
status, repo/git state, unfinished work, session issues, and the
recommended next-session prompt plus tracker/incident item recommendations.

Done when: every section below has a value, never a placeholder left
un-filled; the next-session prompt includes a `/goal` statement (a real goal
statement, not a bare task list); and items already tracked are prefixed
with their bare identifier instead of restated as new. Exact dashboard
template, the "already tracked" shape, and the bare-`#NNNNN`-is-fine
exception for this report only:
[references/output-format.md](references/output-format.md#step-5-dashboard-template).

Both the tracker-items and incident-tickets lists are **recommendations**;
`track-followups` creates them and reports the resulting identifiers.

---

## Related Skills

- **handoff** (mattpocock/skills, installed through nix-ai) — users may explicitly
  invoke it for a portable Markdown document in the OS temporary directory.
- **goal** (this plugin) — the objective alone, when you want direction rather
  than progress.
- **wrap-up** (this plugin) — session-completion verdict; calls this skill for
  Step 0 and handles conditional repository cleanup.
- **track-followups** (this plugin) — consumes Step 4's triage and actually
  creates the tracker and incident items this skill only recommends.
- **resume** (this plugin) — cold pickup; reuses this skill's derivation.
- **replan** (this plugin) — rebuilds a plan this skill shows has drifted.
- **refresh-repo** (github-workflows) — Checks PR merge-readiness and syncs local main.
- **prune-branches** (github-workflows) — Deletes stale branches and worktrees.
- **retrospecting** (claude-retrospective) — Generates detailed retrospectives
  based on session logs and git diffs.
- **local-subagents** (ai-delegation) — the router mechanics used by "Delegate the bulk read": live model menu, tier choice, and the fallback rule.