/orient

name: orient
description: >-
  Orient a spec-driven jig/servo/shaper repository with a read-only, project-wide
  briefing: start from the `workflow.py orient` headline, then survey open pull
  requests and unmerged work, Proposed ADRs, DEFERRED triggers, refinement items,
  release plans, the inbox, and the bug board; render one readable headline,
  titled sections, one recommendation, and an
  owning-skill handoff. Use when the user invokes `/jig:orient` or explicitly asks
  for a whole-project session pickup, a return-after-time-away briefing, the overall
  project status or big picture, or what to pick up next across the repository. Do
  not use for mid-implementation questions about the current slice such as "what's
  next?" or "what's blocking this test?"; those continue current work rather than
  requesting a project-wide rescan. Also do not use for non-code projects; use
  `studio:project-desk`. Never write files or lifecycle state; scheduled jobs and
  dashboards may capture stdout.

Orient

**One job: tell the user where the project stands and what to do next, in a shape they can actually read.**

The user runs `/jig:orient` (or asks to be oriented) — the calm manager's question, *"where do things stand, and what should I pick up?"* Orient answers it by reading the project's own truth (not guessing), and presenting it in **one fixed, scannable layout**: a headline that tells the honest state, then a short stack of **titled sections**, each a list of **titled bullets** — never a wall of inline prose with items buried mid-sentence.

The substance is grounded; the **format is the point**. If the answer reads like a paragraph with five things crammed into it, the skill has failed even if every fact is right.

This is a **project-level rescan**, not a mid-flow nudge. A bare conversational *"what's next?"* while actively implementing a slice is asking to continue that slice — not to re-survey the whole project. Orient is for the deliberate "step back and take stock" moment (an explicit `/jig:orient`, a session pickup, a "where are we overall").

---

Start from the deterministic headline

Do not re-derive the project's lifecycle state by hand — jig already computes it. Run the read-only command spec 088 added and use its line as your factual base:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/spec-workflow/workflow.py" orient --project-dir . --fetch
# → jig hint: <scaffold state> · active specs: <rollup> · focus: <slice needing attention>
#   …and, only when the checkout is ahead of its default branch:
#   · in flight: <n> commit(s) ahead of <base> on <branch>
#   …and, only when the --fetch check finds a problem:
#   · freshness: <n> commit(s) behind <base>   |   could not reach origin

Pass **`--fetch`**. Orient reads *local* boards, ADRs, and slice `STATUS` — all only as current as your last fetch — so an interactive orientation must refresh against origin first, or it will confidently narrate a stale picture (work already shipped on trunk reported as still open). `--fetch` runs one bounded, fail-soft `git fetch` and adds a `freshness:` segment when the checkout is **behind** origin, or when origin **could not be reached** (offline: the local view is unverified, not confirmed fresh). This flag is for the interactive path only — the SessionStart hook never passes it (spec 103's git-freshness hook already fetches at time-zero), so the hot-path headline is unchanged.

That single `jig hint:` line — scaffold classification, active-spec rollup, and the slice currently requiring lifecycle attention — is the **deterministic headline**. Reusing it (rather than re-implementing a second lifecycle-focus algorithm) keeps Orient's headline from drifting away from jig's own computed state. Orient's job is to **layer judgment on top**: the ADRs, deferrals, release plans, refinement-todo, inbox, and standalone bugs that the one-line command does not weigh, then recommend one thing.

**If the headline shows `freshness: … behind …`, treat every local artifact below as possibly stale** — say so in the headline, and recommend integrating origin (or re-running after a pull) before trusting the boards. A `could not reach origin` reading means you could not verify freshness at all; report that honestly rather than implying the state is current.

---

The prime directive — formatting

These rules are non-negotiable. They are the reason this skill exists.

• **Every distinct item is its own bullet, led by a short bold title.**

`- **Recents (002-07)** — the last fork of the quick-add split; needs a Home-row mockup first.` Never `favourites are done and recipes are done but recents still needs a design and also backup restore is parked and…`

• **Group bullets under `##` / `###` section headers.** The reader should be able to

jump to "the deferred stuff" or "the one decision" by scanning headers alone.

• **No inline lists.** If you catch yourself writing "X, plus Y, and also Z" where X/Y/Z

are separate pieces of work, stop and turn them into three bullets.

• **One line per item where possible.** Title — what it is — the blocker or trigger.

Keep each bullet to roughly one sentence; detail goes in a sub-bullet only if it earns it.

• **Lead with the answer.** The headline and the obvious next step come first, before any

exhaustive lists.

• **Omit empty sections.** Only render a section if it has real content. A project with no

pending ADR simply has no "one decision" section — don't print an empty heading.

If you honor nothing else here, honor this section.

---

What it reads (the survey)

Orient is **read-only reconnaissance**. The deterministic headline (above) already gives you scaffold state, active-spec rollup, and current focus. Layer the judgment survey on top.

**First, resolve the docs root — don't hardcode `docs/`.** Read `layout.docs_root` from `<project>/scaffold.json` (the canonical resolver is `_common/project_layout.py`; the default is `docs`, and a value of