orient

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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 `.` collapses the docs layer so artifacts live at the
repo root). Call the resolved value `<docs_root>` and read everything below relative to
it — with `docs_root="."`, `<docs_root>/specs/` is simply `specs/`. Skipping this makes
Orient report "no spec-driven project" on a perfectly valid track-local repo.

Projects vary, so look for these, use what exists, don't assume they all exist:

- **Open pull requests — check these FIRST, and never skip them.** Run `gh pr list`
  and **read the body** of each open PR (`gh pr view <n>`): unattended workers —
  overnight, cron, servo loops — put their questions-for-the-owner in the PR
  description and nowhere else. For each, note what it asks for, whether it is stale
  against newer local commits, and whether its branch is already an ancestor of local
  work. If `gh` is unavailable, unauthenticated, or the repo has no remote, **say so in
  one line** rather than silently omitting the section — "could not check" and "nothing
  waiting" are different answers.
- **Spec status** — `<docs_root>/specs/<MNN-slug>/` slice files and the spec status board
  `<docs_root>/specs/README.md`. Read each slice's STATUS marker: `DRAFT`,
  `READY_FOR_REVIEW`, `READY_FOR_IMPLEMENTATION`, `IN_PROGRESS`, `REVIEWED`, `RECONCILED`,
  `DONE`, `DEFERRED`, `ABANDONED`. This is the spine of "what's shipped vs. open."
  (`workflow.py orient` already summarizes the active rollup — use it rather than
  recounting from scratch.)
- **Use-case progress** — only when `<docs_root>/product-vision.md` has a `## Use cases`
  section: run the read-only
  `python3 "${CLAUDE_PLUGIN_ROOT}/skills/spec-workflow/workflow.py" progress --summary --project-dir .`
  and use its output for the briefing's Use-case progress section. It writes nothing,
  and it is a progress view, not a check that the work is on-goal. If it prints a
  one-line `skipped` or `no-op` note (no vision file, no section, or one not elicited
  yet), drop it and

From ramboz/jig, MIT.

More from ramboz/jig