# Situate > Gain situational awareness — read the branch, its diff, its PR, its tickets, and the project's own conventions, and report where the work stands - Skill: `tony/situate` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tony/situate` - Raw SKILL.md: https://api.skillmd.com/api/skills/tony/situate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tony (https://skillmd.com/u/tony) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tony/situate --- # Situate Answer one question: what is going on here, right now, and what would someone picking this up need to know before touching anything. Read `references/situation-sweep.md` first; it defines the six evidence layers, how each degrades, and the read-only contract. Read `references/prior-conversations.md` before using `--with-agentgrep`. User arguments: $ARGUMENTS ## Context Repository — run this command and read the output: ```bash git remote get-url origin 2>/dev/null || echo "(no remote)" ``` Current branch — run this command and read the output: ```bash git branch --show-current 2>/dev/null || echo "(detached HEAD)" ``` Trunk — run this command and read the output: ```bash git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo "(origin/HEAD unset)" ``` Ahead / behind trunk — run this command and read the output: ```bash git rev-list --left-right --count "$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo origin/main)"...HEAD 2>/dev/null || echo "(no comparison available)" ``` Working tree — run this command and read the output: ```bash git status --short 2>/dev/null | head -20 || echo "(unavailable)" ``` Trunk ref last updated — run this command and read the output: ```bash git log -1 --format='%cr' "$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo origin/main)" 2>/dev/null || echo "(unknown)" ``` ## Procedure ### 1. Fix the scope Default scope is the current branch measured against trunk, plus its pull request if one is open. `--pr ` switches the subject to that pull request and its head branch instead — for reviewing someone else's work, or returning to a branch not currently checked out. Read it through `gh`; do not check it out. On trunk with nothing ahead and a clean tree, there is no branch story. Report recent trunk activity and the open pull requests, and say that is what happened. ### 2. Sweep the layers Work through the five repository layers in the order the sweep reference sets out: position, change, pull request, tickets, conventions. Gather all of them before writing anything — a finding in one layer changes what matters in another, and a ticket's acceptance criteria reframe the diff that implements them. ### 3. Search prior conversations Only with `--with-agentgrep`, and only under the rules in the prior-conversations reference: scoped to this project, capped, checked against the repository, and reported without local paths. Derive the search terms from what the first four layers found unless the user supplied them. ### 4. Report Write the sections below, in order. Then hand back — this command ends at understanding. ## Rules - Read-only. No commits, no pushes, no edits, no stashes, no branch switches, and no `git fetch`. - Report absence explicitly. "No pull request open" is a finding; a missing section reads as a layer that was never checked. - Separate what was read from what was inferred, and mark the inferences. - Cite only ticket IDs found in the commits, the branch name, or the pull request body. Never invent a reference. - Prior conversations are evidence of intent; the repository is the evidence of state. When they disagree, the repository wins and the disagreement is worth reporting. - Orient, do not fix. Failing checks, review threads, and dirty files get surfaced, not repaired. - No local absolute paths and no third-party personal details in the report. ## Output Open with a one-line hero — `✓ : · commits · PR # `, or `⚠ ` — then exactly these sections: 1. `## Position` — branch, trunk, ahead/behind, uncommitted work, stashes, and how stale the trunk ref is. 2. `## Change` — what the branch does and how far along it is, grouped by area, with the commit sequence's shape. 3. `## Pull request` — state, checks by job name, unresolved review threads and what they ask for; or that none is open. 4. `## Tickets` — each linked issue with its state and what it asks for; or that none is referenced. 5. `## Conventions` — the rules from AGENTS.md / CLAUDE.md that bear on this change, and the quality gates it must pass. 6. `## Prior work` — only when `--with-agentgrep` ran: what was decided earlier, when, and whether the repository agrees. 7. `## Open questions` — what is unresolved, mid-flight, or contradictory, and what a resumed session would most likely get wrong. End with an `ask-user-choice` panel offering next steps (for example: continue the branch's work, address the review threads, open a pull request, widen the sweep to prior conversations) — skip the panel only in plan mode. ## Portability notes - `ask-user-choice` — present the listed options and wait for the user to pick one. Hosts with a structured multiple-choice tool (Claude Code's `AskUserQuestion`) should use it; otherwise print a numbered list and wait for a numbered reply. Never proceed on an assumed answer. - `$ARGUMENTS` — the text the user passed when invoking this skill. If your host does not substitute it, read it as the user's request in the current turn, and ask when there is none. - Bundled files — every relative path in this skill points at a file shipped inside this skill directory. Read them from here, not from the host's plugin tree.