/orient

name: orient
description: Internal skill for commands. Render the shared orientation snapshot - active task, what's in flight, what's next - tracker-universal. Do not trigger on user conversation; only when a command needs the snapshot.
user-invocable: false

Orient Snapshot

Render the shared "where am I / what's in flight / what's next" snapshot. Consumed by `/lets:status` (snapshot, then stop), `/lets:start` (snapshot + pick/claim), and `/lets:backlog --fast` (snapshot + dialog). Single source of truth so the three never drift.

> This skill ONLY gathers + renders the snapshot block. It does NOT select, claim, mutate, or advise. The caller appends its own follow-through.

Built on git + `detect-task` + neutral tracker verbs, so it degrades cleanly on any tracker (`beads` | `none` | a custom adapter).

> **IMPORTANT:** If the spec below invokes any deferred tool (e.g. `AskUserQuestion`), you MUST load and call it as specified. Never skip the call, never substitute a default answer of your own - the tool invocation is part of the contract.

Step 1: Active task

Invoke `Skill(skill: "lets:detect-task")` -> an id or None. (A skill may invoke another skill; this is a normal nested `Skill`-tool call in the same orchestrator context.)

**Inline fallback** (only if the nested `Skill` call is unavailable - rare: skill-invokes-skill is sound, this is belt-and-suspenders): do NOT re-derive the id with a partial copy of detect-task's precedence ladder (it would rot when the branch format changes and would drop detect-task's merge-branch liveness check + its search-and-confirm fallback). Instead skip the active-task line and note it degraded - the In flight section (Step 3) still surfaces any in_progress task. `detect-task` stays the single source of branch-format truth.

When Step 1 yields an id, get its title with the tracker's `show`:

show task=<id>   # returns {id, title, status, url}

Step 2: Git state

git branch --show-current
git status --short   # empty = clean; else count the lines

Detect context (one compact line, only if applicable): worktree (git-dir contains `worktrees/`), trunk-mode (HEAD == `{LETS_MERGE_BRANCH}` AND an active task), or main-mode (HEAD == `{LETS_MERGE_BRANCH}`, no task).

Step 2.5: Peers

The caller passes `caller=status|start|backlog` (default `status`).

LETS_PROJECT_ROOT=$(git rev-parse --show-toplevel)
ls "$LETS_PROJECT_ROOT/.lets/sessions/peers/"*.role >/dev/null 2>&1 && echo PEER_EVIDENCE=roles
lets peers who --exclude-session "$CLAUDE_CODE_SESSION_ID" --timeout-ms 2500 --json 2>/dev/null || echo '{"ok":false}'

Evidence = `PEER_EVIDENCE=roles`, or at least one row in `peers`. With evidence: render `## Peers` (Step 6) plus one line per `degraded[]` entry. Without evidence: caller `status` prints only the degraded line(s) (nothing when every source is healthy); callers `start` / `backlog` omit the block. `{"ok":false}` (no binary, a stub) counts as no evidence and no degraded line.

Step 3: In flight

list-by-status status=in_progress

Mark the active task (from Step 1) with ` <- active`. If `{LETS_PR_FLOW}` == github, add open PRs:

gh pr list --state open --author @me --json number,title,url,reviewDecision --limit 5 2>/dev/null

Step 4: Next up (flat top-N ready)

ready limit=5   # fallback if the tracker marks `ready` absent: list-by-status status=open limit=5

Priority-sorted, NOT grouped by label. If more than 5 ready, note `(+N more ready)`.

Step 5: Project counts (OPTIONAL - adapter capability)

Use the tracker's `stats` capability for the totals - do NOT hand-roll per-status counts or `jq` over task JSON (that fragile path is exactly what this redesign removes).

stats

• beads -> read the totals `bd stats` already computes (open / in_progress / closed) - native, correct, no pagination risk.
• a tracker whose `stats` is `partial` -> OMIT the block in v1.
• none -> `stats` is absent; OMIT the block.

If the active adapter marks `stats` absent, OMIT the `## Project` section entirely - never render an empty/broken block.

Step 6: Render

## Where you are
Branch: `{branch}`  -  {Task: **{title}** (`{id}`) | no active task}  -  {clean | {N} uncommitted}
{context line: worktree / trunk-mode / main-mode - only if applicable}
{Tracker: none - task tracking off   - only when the active tracker is `none`}

## In flight
- **{title}** (`{id}`){ <- active}
- PR #{n} **{title}** - {reviewDecision or pending}     {github only}
{if none: "Nothing in flight."}

## Next up
  P{n}  **{title}** (`{id}`)
  (+{N} more ready)
{if none: "No ready tasks."}

## Project                                               {only if stats present}
{open} open - {wip} in progress - {closed} closed

## Peers                                                 {per Step 2.5}
| role | name | scope / orchestrator | task | branch | state | last activity |
|------|------|----------------------|------|--------|-------|---------------|
| {role or -} | {name} ({session6}) | {an orchestrator's scope | -> {a worker's orc}} | {task} | {branch} | {state; "liveness unknown" when alive=unknown} | {last_activity} |
via {orca | claude registry | orca + claude registry}
{claude registry: <reason> (<detail>)  |  orca: <reason>   - one line per degraded source}
{both sources down: "Peers: unavailable - <reason>; <reason>"}

On the `none` tracker, In flight / Next up / Project have no data source - omit those three sections and show only `## Where you are` + the `Tracker: none` line.

Rules

• Read-only. Never mutate, never claim, never advise - the caller owns follow-through.
• Every task reference is `**Title** (`id`)`, never a bare id.
• Respond in the user's language.
• Degrade section-by-section; a missing capability drops its section, never the whole snapshot.
• Peers is gated on evidence, and `/lets:status` always surfaces a degraded transport - a n