# Situate Situational Awareness > Use when you came back to a branch/PR: the work you were in the middle of, where it left off, repo state, and what reviewers ask or the PR waits on. - Skill: `tony/situate-situational-awareness` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tony/situate-situational-awareness` - Raw SKILL.md: https://api.skillmd.com/api/skills/tony/situate-situational-awareness/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tony (https://skillmd.com/u/tony) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tony/situate-situational-awareness --- # Situational awareness Establish what is going on in a repository before acting in it: what the branch does, how far along it is, what its pull request and tickets ask for, and what the project's own rules require of the work. Two reference files carry the parts that must not drift between this skill and `/situate`: - `references/situation-sweep.md` — the six evidence layers, how each one degrades, and the read-only contract. - `references/prior-conversations.md` — when searching local AI transcripts is warranted, how to scope it, and what may not appear in the report. A bare "huh" or "what?" is not this skill. That is disorientation looking for five lines, and the `brief` skill answers it; the `situate-what` skill is its explicit form. This one runs when someone can already say what they want caught up on and wants the whole picture. ## Core principle Read everything before reporting anything. The layers reinterpret each other. A ticket's acceptance criteria change what the diff means. An unresolved review thread explains a commit that otherwise looks like a detour. Reporting each layer as it arrives produces a list of facts; reading them together produces a situation. ## Read-only No commits, no pushes, no edits, no branch switches, no `git fetch`. This runs at the start of a session, before the user has decided anything. A command that mutates while claiming to orient is worse than no command at all — it changes the state being reported on, and it does so before there is any agreement about what should change. ## Phase 1 — Position Branch, trunk resolved from `refs/remotes/origin/HEAD` rather than assumed, merge-base, ahead/behind counts, uncommitted work, stashes. Uncommitted work is the highest-signal part of this phase. It is the piece of the situation that no commit, pull request, or ticket records, and the piece a resumed session is most likely to trample. ## Phase 2 — Change Commits since the merge-base, and the diff behind them. Report intent — what behavior changed and what the sequence was building toward — not an inventory of paths. The shape of the history is itself evidence: pending fixups, a revert, a mid-branch merge from trunk. Each says something about where the work stands. ## Phase 3 — Pull request and review State, checks by job name, review threads and what they ask for. Verify that a green check rollup covers the current head rather than an earlier push. Review threads are the only layer holding another person's opinion, and the one a resumed session has least chance of reconstructing on its own. ## Phase 4 — Tickets IDs from commits, branch name, and pull request body only. Resolve GitHub issues through `gh` and other trackers through whatever MCP server the session has connected. An ID that cannot be resolved is reported unresolved. ## Phase 5 — Conventions The rules in `AGENTS.md` and `CLAUDE.md` that bear on this change: commit format, quality gates, constraints on the files being touched. Nested files override the root for their subtree. Report the rules that apply to the work in flight, not the whole document. ## Phase 6 — Prior conversations Opt-in. Warranted when the repository does not explain itself — an approach with no recorded rationale, work resumed after a gap, a decision that left no artifact. Follow the prior-conversations reference for scoping, capping, reconciliation, and privacy. ## Report Lead with what is unresolved. Someone asking to be caught up wants the open questions, the failing check, and the half-finished edit — not a narration of what already works. Separate what was read from what was inferred, and say which layers were unavailable and why. ## Common mistakes **Acting on the situation instead of reporting it.** Fixing a failing check mid-sweep changes the state being reported and pre-empts a decision the user has not made. **Assuming trunk is `main`.** Resolve it from the remote; the fallback is a guess and gets labeled as one. **Fetching to freshen the comparison.** It rewrites remote-tracking refs and changes what the rest of the session sees. Report the ref's age instead. **Reporting a file inventory as the change.** The diff already lists paths. What is missing is what the branch is for. **Treating a prior conversation as current state.** A plan discussed weeks ago may have shipped, been abandoned, or been reversed — and the transcript reads identically in all three cases. **Silently omitting an empty layer.** A dropped section and an unchecked one are indistinguishable to the reader. **Trusting a stale check rollup.** Green on a run that predates the last push says nothing about the current head. ## Portability notes - 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.