| name | session-status |
| description | Analyzes current session state and repository status without any cleanup. Full mode (default): resolves the active plan file, reads plan checklist + TaskList, gathers unfinished work/issues from conversation history, checks git status, and emits a /handoff-built next-session prompt. Mid-session mode (`/session-status mid`): a fast plain-language 'done vs remaining' snapshot for mid-flight orientation, skipping the history scan, triage, and handoff. |
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:
- Resolve the plan file (Step 1a) and read its open checklist items with line
numbers. Call
TaskList.
git status -sb in the cwd; note branch and ahead/behind.- Count done vs remaining across both the plan checklist and
TaskList.
- Print the compact snapshot — plain language, no dashboard:
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>)
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:
- Scan the current conversation context for
<system-reminder> blocks whose
body contains a path matching the regex
[^[:space:]]+/\.claude/plans/[^[:space:]]+\.md.
- If multiple matches exist, take the most recently quoted one — latest
in conversation order.
- 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
other sessions' transcripts.
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
Perform git and GitHub checks to locate active changes and remote state:
-
Run git status to identify modified/untracked files and the current branch
name.
-
Determine if the current branch has unpushed commits or is out of sync with
its remote tracking branch.
-
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.
-
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.
-
Validation follow-up (refs dryvist/ai-assistant-instructions#749): for
every open PR this session authored (branch name or PR body carries this
session's id, plus any PR created in this conversation), check the
agent-validated commit status on the current head SHA:
head_sha=$(gh pr view <n> --json headRefOid --jq '.headRefOid')
gh api "repos/{owner}/{repo}/commits/$head_sha/statuses" \
--jq '[.[] | select(.context == "agent-validated")][0].state'
Flag as needs follow-up: no agent-validated status on the head SHA
(unvalidated, or validated evidence went stale when new commits landed),
state failure, or the PR is validated but sitting unmerged. These are
enforced follow-ups — they go in the report and, when unfinished, into
the next-session prompt or a GitHub issue (Step 4).
Step 4: Triage and Recommendations
Split the gathered items into three buckets:
- Next-session prompt — items small enough to complete in a single focused
session (roughly 1–3 tasks). Combine related items where possible.
- GitHub issues — code, config, or repo defects and features: something in
a repository has to change. Before recommending new issues, search existing
open issues with
gh issue list --state open --json number,title,url for
duplicates. Use full URLs for references.
- Zammad tickets — operational/incident-shaped items: a production or
infrastructure anomaly, an RCA- or postmortem-worthy event, or something a
runbook should have caught. Zammad is the org's incident system of record;
these do not become GitHub issues. If the
mcp__zammad__* tools are
available this session, search for duplicates first with
zammad_search_tickets — same shape as the gh issue list dedup check
above. If those tools are not configured this session, skip the dedup check
and say so explicitly; never guess a ticket number or state.
An item that is both (e.g. a bug that caused an outage) gets split: a Zammad
ticket for the incident, a GitHub issue for the underlying code fix, each
referencing the other.
Step 5: Output Format
Present the final status analysis in the following structured dashboard:
Session & Repository Status Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Active Plan:
Plan File: <plan-file path or "none">
Status: <complete | incomplete | "no plan file found">
Progress: <n> of <m> checklist items completed
Open Items: <list open checklist items with line numbers, or "none">
Harness TaskList:
Status: <complete | incomplete | "empty">
Open Tasks: <list open tasks, or "none">
Git & Repository Status:
Current Branch: <branch-name>
Sync Status: <ahead/behind/up-to-date with remote>
Modified Files: <list of modified/untracked files, or "clean">
Associated PR: <PR URL or "none found">
Validation: <per session PR: agent-validated success | FAILURE | MISSING on head SHA; or "no session PRs">
Unfinished Work & Future Tasks:
- <item 1>
- <item 2>
Session Issues Log:
- <error/warning/workaround encountered>
Recommended Prompt for Next Session:
─────────────────────────────────────
<Build this by invoking the `/handoff` skill with the triaged 1–3 quick-win tasks
as source. `/handoff` returns a `## Goal statement` (capped under 4000 chars,
measured with `wc -c`) plus a `## Full prompt` — paste both here. This guarantees
the next-session prompt carries a real goal that drops into `/goal`, not a bare
task list. Include the resolved plan file path (~/.claude/plans/<slug>.md) so the
new session can re-enter plan mode against it.>
─────────────────────────────────────
Recommended GitHub Issues:
─────────────────────────────────────
1. <Title> — <one-line summary> [new | update <issue-url>]
─────────────────────────────────────
Recommended Zammad Tickets:
─────────────────────────────────────
1. <Title> — <one-line summary> [new | update <Zammad ticket URL> | dedup not
checked — Zammad MCP unavailable this session]
─────────────────────────────────────
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If every item in the "Unfinished Work & Future Tasks" section above is already
a tracked Zammad ticket, write the heading as
Unfinished Work & Future Tasks (tracked in Zammad, not GitHub): and prefix
each item with its bare ticket number, matching this shape:
Unfinished Work & Future Tasks (tracked in Zammad, not GitHub):
- #17053 <one-line description>
- #17058 <one-line description>
This is a live, human-facing report, not a cold-start artifact — a bare
#NNNNN here is fine. The "always full URL, never bare #123" rule applies
to handoff and wrap-up's resume blocks, not this dashboard.
Related Skills
- handoff (git-workflows) — builds the goal-bearing next-session prompt that
full mode's "Recommended Prompt for Next Session" section emits.
- wrap-up (system) — Wraps up the session, performs repository cleanup, and
handles PR purging.
- refresh-repo (github-workflows) — Checks PR merge-readiness, syncs local
main, and cleans worktrees.
- retrospecting (system) — Generates detailed retrospectives based on
session logs and git diffs.
