Claude Skill

orient-gaps

Answers "What is stuck or missing?" on any subject — blockers (on you vs on others), open forks, loose ends, and inferred silent gaps, computed fresh via a bounded read-only subagent. `--audit` raises claim-vs-evidence + gamed-signal disclosure. Trigger phrases: "/orient-gaps", "

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download allemaar-open-skills-skills_orient-gaps-acf5f79.zip · 42 KB

Install

skills CLI npx skills add https://github.com/allemaar/open-skills/tree/main/skills/orient-gaps
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
Git git clone https://github.com/allemaar/open-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

/orient-gaps

What is stuck or missing? Answers with — blockers (on you vs on others) · open forks · loose ends · inferred silent gaps · (--audit) unbacked claims. Does not answer — how far along (/orient-status) · what changed (/orient-map) · what comes next (/orient-roadmap). Owns for the family — the stall surface and the anti-Goodhart audit tier.

Computes a fresh, honest read of what is stuck and what is missing — blockers, open forks, loose ends, and the inferred silent gaps — and returns it as one ephemeral bundle (a structured YON record + a human markdown read + a small visual). --audit adds a second tier: claim-vs-evidence mismatches and gamed-signal disclosure ("don't trust the orientation"). Part of the orient- family; emits the gaps slice of the shared record at references/orient-spec/orient-record.yon.

Structured execution spec: protocol.yon. Read it for the canonical steps, rules, and gates; this file is the human-readable, self-sufficient explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date.

The shared record, render contract, worked fixtures, and value validator travel inside references/. The repository-only round-trip guard is release evidence; its absence from an installed copy does not block execution.

Reuse the shared topology-detection contract within the same single bounded worker, or consume supplied topology fields with their stated provenance and limits. Do not invoke another self-orchestrating orientation skill or start a second sweep; supplied and detected interpretations must agree or remain an explicit gap.

When to use

  • "What's stuck / what's blocking / what's not done / what's missing" on a project, repo, plan, or task.
  • Before trusting a status read — to see whether the bearings rest on anything solid.
  • --audit: "don't trust the orientation" — raise claims that lack evidence and metrics that look inflated.

How it works (self-sufficient — works without protocol.yon)

orient-gaps delegates the gathering to a bounded, read-only subagent so the calling session (a human's, or an agent orienting itself) never sees the search/inference noise — only the result bundle comes back. Nothing is stored; every call recomputes from current reality. If its worker is unavailable, refuses or times out, report unavailable/partial evidence; do not infer NO SUBSTRATE, gather inline, retry or extend the bound. Limit unchanged/clean claims to checked inputs and disclose unexamined tiers. The stall surface and the silent gaps are two tiers of one sweep; --audit raises a third.

  1. Take intent as input, never prompt for it. Intent (the goal / what "done" means) is what makes a gap legible — a loose end is only loose against a goal. Accept an intent argument if given. If intent can't be grounded, gate the goal-relative gaps (render — (needs goal), cap to guessed) and surface only the evidence-attested stalls (uncommitted files, unmerged branches). Never fabricate a goal and hang invented gaps off it.

  2. Spawn one bounded subagent (read-only, depth-1, single wave; budget ≤ ~8–12 tool calls, hard timeout ~60–90s, stop at the first evidence tier that gives a confident answer). It runs the cheap-first evidence ladder and returns this signal (not raw logs):

    • git tier → uncommitted/untracked files (loose_ends), unmerged branches and unresolved conflicts (open_forks), stale branches.
    • plan/doc tier → unchecked blocking items, TODO/FIXME/@blocked markers, an item that names a dependency on someone/something else (blocked_on_other) vs one you own (blocked_on_me).
    • conversation/folder tier → a decision raised but never recorded (an open_fork), a thread dropped mid-way. Every attested gap comes back with a re-runnable source:line/git-ref proof.
  3. Compute two tiers (always):

    • Stall surface — blocked_on_me vs blocked_on_other (attribute from evidence, never assume), open_forks (unresolved decisions), loose_ends (uncommitted/untracked). Set stall_status = stalled when something blocks; otherwise ready.
    • Silent gaps — the honest-negative: what is plausibly missing but unproven (no tests next to new code, a doc that wasn't updated). Always emitted explicitly — silently omitting it implies false completeness. Mark each ◐ inferred or ◌ guessed; never present a silent gap as a confirmed fact.
  4. --audit mode — the third tier ("don't trust the orientation"):

    • audit_mismatches — a claim with no corroborating evidence. Treat missing commits or test files as mismatches only when the actual acceptance contract requires them; otherwise inspect valid uncommitted artifacts, manual results or external records within the same read bound. A missing proxy alone is a gap in evidence, not proof the work was not done..
    • gamed_signals — a metric inflated past its evidence weight (a commit count padded by whitespace-only commits; "activity" with no substantive diff). Tier-tag the hollow signal ◌ so it reads as hollow — the anti-Goodhart disclosure (see references/orient-spec/family-behaviors.md §4).
  5. Tag every field with a provenance tier — ◆ git-attested · ◐ inferred · ◌ guessed — and fail closed: set gate_status (enum: ready | blocked | stalled | degraded | indeterminate) to degraded/indeterminate with a sentinel — never a plausible ready — on barren evidence. An empty stall surface is a success state (collapse to one line: "nothing stuck — clean"), NOT a failure.

  6. Emit the bundle to the consumer that asked — one record, three faces, never all three at one reader. The YON record is the AGENT face and goes to an agent consumer only; a human gets the plain-language read plus the visual (widget when available, ASCII twin otherwise) and never sees the record, a raw record field, a node-id, or a gate enum. See Record emission below for the YON face (agent-only); the markdown read follows the worked examples; the visual face is rendered per the render-face contract §6 (Claude Code only): for a human on Claude Code with the visualize tool present on an explicit invocation, build the gaps widget from the kit — call mcp__visualize__read_me once, then emit via mcp__visualize__show_widget an HTML stall board (per orient-contract.md §2 "gaps = a stall board / sieve — the hole is the deliverable"): a 4-lane grid (blocked · open-forks · loose-ends · silent-gaps), each item carrying a muted effort S/M/L tag, empty lanes shown as — clear (the honest-negative, never omitted), the "you are here" breadcrumb on top (↳ in: {parent_subject}, omitted when absent), ◆◐◌ tier glyphs as redundant non-color encoding, and the legend ◆ attested · ◐ inferred · ◌ guessed · effort S·M·L · — honest-negative. HTML chrome: colors only via CSS vars (no hardcoded hex), no position:fixed, and a visually-hidden <h2 class="sr-only"> one-sentence summary for a11y. An agent consumer gets the YON record only; any other runtime / no tool / indeterminate handler_type gets the ASCII twin (fail-closed). The information-complete ASCII stall-board twin is emitted when the selected face includes a visual — it is the only render in a no-SVG channel and carries every lane item the widget does. Token discipline: a clean result collapses to one line. The footer is one evidence-derived line — and only ever suggests a skill that is actually installed (a blockers_present reason_code routes to /plan-create; an unwritten_decision routes OUT to an installed durable-capture skill per the family handoff-feeder).

Record emission (the YON face — AGENT consumers only; never printed to a human)

Before emission, pipe the actual current record in memory to node <skill-dir>/references/tools/orient-validate.mjs -. Do not save a derived record or substitute an example/self-test pass. The helper covers mapped enums, core/schema-version fields, parsing/duplicates, provenance syntax and barren status, with an ETA point warning; all other emitter obligations still apply. Select the consumer face before applying visual/trailer requirements: agent record-only, automator no visual, nominal human auto-loop one line, explicit human full face, unknown consumer ASCII fallback; preserve the widget escape.

The structured face is the gaps slice of references/orient-spec/orient-record.yon (schema_version = orient-record/1). Reserved tags only — custom tags are parser-rejected. List fields (blocked_on_me, blocked_on_other, open_forks, loose_ends, silent_gaps, audit_mismatches, gamed_signals) go in a sidecar @MAP, never an in-set bracket-list (an in-set bracket-list corrupts the record silently and still validates). Never run yon format on an emitted instance — CANON mode is destructive on set-internal lists. Validate with --profile exec. Minimal skeleton:

@CFG id=orient | set=[schema_version=orient-record/1,computed_at:ts=…,ephemeral:bool=true,tool=orient-gaps,tier=orient,scope=…,evidence_mode=git-only,gate_status=stalled,gate_blocking_field=loose_ends,gate_confidence_floor=git-attested,family_used=orient-gaps,family_suggested_next=plan-create,family_reason_code=blockers_present,overall_trust=med,degraded:bool=false]
@CFG id=subject | set=[name=…,kind=monorepo,purpose=…,purpose_source=readme,intent_status=stated,parent_subject=…]   # parent_subject drives the ↳ in: breadcrumb; omit the field (and the breadcrumb) when absent
@CFG id=gaps | set=[stall_status=stalled]
@MAP name=blocked_on_me | pairs=["b1"->"…"]
@MAP name=open_forks | pairs=["f1"->"…"]
@MAP name=loose_ends | pairs=["l1"->"…"]
@MAP name=silent_gaps | pairs=["s1"->"… (inferred)"]
@MAP name=audit_mismatches | pairs=["a1"->"…"]   # --audit mode only
@MAP name=gamed_signals | pairs=["g1"->"… ◌"]      # --audit mode only
@MAP name=provenance | pairs=["gaps.loose_ends"->"git-attested:high:git-status"]

A full worked instance ships at references/orient-spec/examples/orient-record.example.yon.

Output — worked examples (markdown face)

Rich tier (a repo with real stalls — the ASCII stall-board twin):

🧭 open-skills — public skills repo.   ↳ in: open-source push   [identity: ◆ git]
## Stuck — 1 blocker · 1 open fork · 2 loose ends         ◆ git + plan
┌─ blocked ──────────────┬─ open-forks ───────────────┐
│ ◐ P4 awaiting cold-vet [M] │ ◐ schema_version bump  [S] │
├─ loose-ends ───────────┼─ silent-gaps ──────────────┤
│ ◆ 3 uncommitted, 1 untracked [L] │ ◐ no honesty fixture yet [M] │
└────────────────────────┴────────────────────────────┘
**→ Next:** clear the blocker, then commit the loose ends.
Trust: ◆◐ · ⚠️ lean here: the blocker + fork are inferred (plan TODO / no record); only the loose ends are git-attested · next → /plan-create
legend: ◆ attested · ◐ inferred · ◌ guessed · effort S·M·L · — clear (honest-negative)

Clean tier (nothing stuck — the success collapse; the widget shows every lane — clear):

🧭 some-cli — a git repo on `main`, clean tree.           [identity: ◆ git]
**Nothing stuck — clean.** blocked: — clear · open-forks: — clear · loose-ends: — clear   ◆ git
**Silent gaps:** none surfaced (coarse — git + plan only).  ◐ honest negative
Trust: ◆ · [no observed blocker in checked inputs]

--audit tier (don't trust the orientation):

🧭 some-repo — a git repo on `wip`.                       [identity: ◆ git]
## Audit — 1 claim unbacked · 1 gamed signal              ◆ git
| audit flag      | what                            | from         |
| claim vs evidence | "tests pass" — no test files   | ◌ no evidence |
| gamed signal    | 9 commits, 7 whitespace-only    | ◌ hollow ◌    |
**→ Next:** back the test claim or drop it.
Trust: ◌ · ⚠️ lean here: the "tests pass" claim has zero corroborating evidence.  [limited evidence]

The ASCII stall board + the trust trailer with the ⚠️ lean your scrutiny here line (naming the load-bearing guess) is mandatory on the selected full human face; the silent-gaps honest-negative is never silently dropped.

Boundaries

  • Not /orient-status — that reports position + remaining + ETA (where you stand); orient-gaps reports what's stuck and missing (why you can't trust it / can't move).
  • Not /orient-map — that reports shape + delta (how you got here); orient-gaps reports the stall surface (what's blocking). They share one sweep's evidence, and orient-gaps consumes orient-map's topology (on_branch/fork/open-fork detection) rather than recomputing it.
  • Not /investigate — that gathers arbitrary deep facts read-only; orient-gaps computes a fixed stall + silent-gap + audit surface about ongoing work.
  • Not /reflect, not insight-* — those THINK / DECIDE; orient-gaps only SEES and reports NOW. After it, reach for /plan-create to clear the blockers, or the family handoff-feeder — an installed durable-capture skill — for an unwritten decision.
  • Read-only. It never mutates state; the one sanctioned reference point (an intent line) is caller-supplied or harness-held, never written to disk by default.

Rules

  • MUST compute two tiers from one sweep — the stall surface (blockers / forks / loose ends) and the silent gaps; --audit raises the third (claim-vs-evidence + gamed-signal).
  • MUST emit silent_gaps (the honest negative) explicitly — never silently omit it — and mark each ◐/◌, never as a confirmed fact.
  • MUST attribute blocked_on_me vs blocked_on_other from evidence, never assume; an empty stall surface collapses to a one-line success state, not a failure.
  • MUST take intent as input and gate goal-relative gaps when it's absent — never fabricate a goal or invent gaps off it.
  • MUST tag every field with a provenance tier and fail closed — gate_status = degraded/indeterminate with a sentinel — on zero evidence.
  • --audit MUST tier-tag a gamed signal ◌ so a hollow metric reads as hollow (the anti-Goodhart disclosure).
  • MUST, when the consumer is an agent (handler_type = agent), emit a record conformant to references/orient-spec/orient-record.yon (reserved tags; list fields as sidecar @MAP; never yon format an instance). A human consumer gets its selected plain-language face (one line when nominal, otherwise the read plus visual) — never the record, a raw record field, a node-id, or a gate enum.
  • MUST, when the selected face includes a visual, emit the ASCII stall board + the trust trailer with the ⚠️ lean here load-bearing-guess line; the visual's ASCII twin is mandatory.
  • MUST carry the "you are here" breadcrumb (↳ in: {parent_subject}) on the identity banner in both faces when subject.parent_subject is present — and omit it entirely when absent (never fabricate a parent); per orient-contract.md §1 and family-behaviors.md §8.
  • MUST NOT print the YON record — or any raw record field, node-id, gate enum, @CFG line, or @MAP line — into a human-facing reply. The record is the agent face (handler_type = agent); the human face is the plain-language read plus the visual (widget when available, ASCII twin otherwise). Per references/orient-spec/orient-contract.md §1 (token discipline) and family-behaviors.md §6.
  • MUST render the visual face per the render-face contract (Claude Code only, via mcp__visualize__show_widget): agent → YON record only; human + Claude + tool + explicit invocation → stall-board widget + ASCII twin; other runtime / no tool / indeterminate handler_type → ASCII twin (fail-closed). The gaps widget is an HTML stall board — a 4-lane grid (blocked · open-forks · loose-ends · silent-gaps), each item a muted effort S/M/L tag, empty lanes — clear (honest-negative, never omitted), the breadcrumb on top.
  • MUST keep the widget and ASCII twin projections of one node-structure (same lane items + ◆◐◌ tier glyphs as redundant non-color encoding), HTML-chrome-compliant (colors only via CSS vars — no hardcoded hex; no position:fixed; a visually-hidden <h2 class="sr-only"> summary for a11y), legend ◆ attested · ◐ inferred · ◌ guessed · effort S·M·L · — honest-negative, checked by the repository-only tools/orient-roundtrip.mjs release guard when running from a clone; installed copies retain this as an emitter obligation. The widget MUST be sparse — no per-node prose.
  • MUST delegate gathering to a bounded, read-only, depth-1 subagent and return only the bundle (no raw search noise), with a re-runnable proof on every attested gap.
  • The family footer MUST only suggest an installed skill.

Next skills. On completion, run the Next Skills protocol (next-skills/SKILL.md): surface the next-skills recommendations from front-matter for the caller to pick. Offer only — never auto-invoke.

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.

Files (open-skills)
  • references
    • orient-spec
      • examples
        • bad
          • enum-banana.yon 2 KB · in bundle
          • fail-open.yon 1.6 KB · in bundle
        • orient-record.example.yon 7.1 KB · in bundle
      • family-behaviors.md 10.9 KB
        Loading…
      • family-manifest.yon 7.3 KB · in bundle
      • orient-contract.md 13.8 KB
        Loading…
      • orient-record.yon 15.3 KB · in bundle
    • tools
      • orient-validate.mjs 14.6 KB · in bundle
  • protocol.yon 12.1 KB · in bundle
  • SKILL.md 19.2 KB
    ---
    name: orient-gaps
    description: >
      Answers "What is stuck or missing?" on any subject — blockers (on you vs on others), open forks, loose ends, and inferred silent gaps, computed fresh via a bounded read-only subagent. `--audit` raises claim-vs-evidence + gamed-signal disclosure. Trigger phrases: "/orient-gaps", "what's stuck", "what are the blockers", "can I trust this". Not /orient-status (how far along am I and when will it be done), /orient-map (what changed since I last looked), /orient-roadmap (what comes next and what gates it), or /investigate (deep facts) — orient-gaps shows the STALL surface.
    visibility: public
    self-improvable: true
    companions:
      - path: references/orient-spec
        optional: false
        why: "The required record, render contract, and worked fixtures; bundled inside this skill."
      - path: references/tools/orient-validate.mjs
        optional: false
        why: "The required value and fail-closed gate; bundled inside this skill."
      - path: ../../tools/orient-roundtrip.mjs
        optional: true
        why: "Repository-only release evidence; installed execution retains the emitter obligation."
    next-skills:
      - skill: plan-create
        phrase: "/plan-create"
        why: "Turn the surfaced blockers and loose ends into a phased plan to clear them"
    triggers:
      - "/orient-gaps"
      - "what's stuck"
      - "what's not done"
      - "what's missing here"
      - "can I trust this"
      - "what are the blockers"
      - "audit this orientation"
    ---
    
    # /orient-gaps
    
    > **What is stuck or missing?**
    > **Answers with —** blockers (on you vs on others) · open forks · loose ends · inferred silent gaps · (`--audit`) unbacked claims.
    > **Does not answer —** how far along (`/orient-status`) · what changed (`/orient-map`) · what comes next (`/orient-roadmap`).
    > **Owns for the family —** the stall surface and the anti-Goodhart audit tier.
    
    Computes a fresh, honest read of **what is stuck and what is missing** — blockers, open forks, loose ends, and the inferred *silent gaps* — and returns it as one ephemeral bundle (a structured YON record + a human markdown read + a small visual). `--audit` adds a second tier: claim-vs-evidence mismatches and gamed-signal disclosure ("don't trust the orientation"). Part of the `orient-` family; emits the `gaps` slice of the shared record at [`references/orient-spec/orient-record.yon`](references/orient-spec/orient-record.yon).
    
    > **Structured execution spec:** [`protocol.yon`](protocol.yon). Read it for the canonical steps, rules, and gates; this file is the human-readable, self-sufficient explanation. The two must stay in sync — if you edit one, update the other and refresh the `@STAMP` date.
    
    The shared record, render contract, worked fixtures, and value validator travel
    inside [`references/`](references/). The repository-only round-trip guard is
    release evidence; its absence from an installed copy does not block execution.
    
    
    Reuse the shared topology-detection contract within the same single bounded worker, or consume supplied topology fields with their stated provenance and limits. Do not invoke another self-orchestrating orientation skill or start a second sweep; supplied and detected interpretations must agree or remain an explicit gap.
    ## When to use
    
    - "What's stuck / what's blocking / what's not done / what's missing" on a project, repo, plan, or task.
    - Before trusting a status read — to see whether the bearings rest on anything solid.
    - **`--audit`**: "don't trust the orientation" — raise claims that lack evidence and metrics that look inflated.
    
    ## How it works (self-sufficient — works without `protocol.yon`)
    
    `orient-gaps` **delegates the gathering to a bounded, read-only subagent** so the calling session (a human's, or an agent orienting itself) never sees the search/inference noise — only the result bundle comes back. Nothing is stored; every call recomputes from current reality. If its worker is unavailable, refuses or times out, report unavailable/partial evidence; do not infer NO SUBSTRATE, gather inline, retry or extend the bound. Limit unchanged/clean claims to checked inputs and disclose unexamined tiers. The stall surface and the silent gaps are **two tiers of one sweep**; `--audit` raises a third.
    
    1. **Take intent as input, never prompt for it.** Intent (the goal / what "done" means) is what makes a gap *legible* — a loose end is only loose against a goal. Accept an `intent` argument if given. If intent can't be grounded, **gate the goal-relative gaps** (render `— (needs goal)`, cap to `guessed`) and surface only the evidence-attested stalls (uncommitted files, unmerged branches). **Never fabricate a goal** and hang invented gaps off it.
    
    2. **Spawn one bounded subagent** (read-only, depth-1, single wave; budget ≤ ~8–12 tool calls, hard timeout ~60–90s, stop at the first evidence tier that gives a confident answer). It runs the cheap-first evidence ladder and **returns this signal** (not raw logs):
       - **git tier** → uncommitted/untracked files (`loose_ends`), unmerged branches and unresolved conflicts (`open_forks`), stale branches.
       - **plan/doc tier** → unchecked blocking items, TODO/FIXME/`@blocked` markers, an item that names a dependency on someone/something else (`blocked_on_other`) vs one you own (`blocked_on_me`).
       - **conversation/folder tier** → a decision raised but never recorded (an `open_fork`), a thread dropped mid-way.
       Every attested gap comes back with a re-runnable `source:line`/git-ref **proof**.
    
    3. **Compute two tiers (always):**
       - **Stall surface** — `blocked_on_me` vs `blocked_on_other` (attribute from evidence, never assume), `open_forks` (unresolved decisions), `loose_ends` (uncommitted/untracked). Set `stall_status = stalled` when something blocks; otherwise `ready`.
       - **Silent gaps** — the honest-negative: what is *plausibly missing but unproven* (no tests next to new code, a doc that wasn't updated). **Always emitted explicitly** — silently omitting it implies false completeness. Mark each `◐ inferred` or `◌ guessed`; never present a silent gap as a confirmed fact.
    
    4. **`--audit` mode — the third tier ("don't trust the orientation"):**
       - `audit_mismatches` — a **claim with no corroborating evidence**. Treat missing commits or test files as mismatches only when the actual acceptance contract requires them; otherwise inspect valid uncommitted artifacts, manual results or external records within the same read bound. A missing proxy alone is a gap in evidence, not proof the work was not done..
       - `gamed_signals` — a metric **inflated past its evidence weight** (a commit count padded by whitespace-only commits; "activity" with no substantive diff). Tier-tag the hollow signal `◌` so it reads as hollow — the anti-Goodhart disclosure (see [`references/orient-spec/family-behaviors.md`](references/orient-spec/family-behaviors.md) §4).
    
    5. **Tag every field with a provenance tier** — `◆ git-attested` · `◐ inferred` · `◌ guessed` — and **fail closed**: set **`gate_status`** (enum: `ready | blocked | stalled | degraded | indeterminate`) to `degraded`/`indeterminate` with a **sentinel** — never a plausible `ready` — on barren evidence. **An empty stall surface is a success state** (collapse to one line: *"nothing stuck — clean"*), NOT a failure.
    
    6. **Emit the bundle to the consumer that asked — one record, three faces, never all three at one reader.** The **YON record is the AGENT face and goes to an agent consumer only**; a **human gets the plain-language read plus the visual (widget when available, ASCII twin otherwise) and never sees the record, a raw record field, a node-id, or a gate enum**. See *Record emission* below for the YON face (agent-only); the markdown read follows the worked examples; the **visual face is rendered per the [render-face contract](references/orient-spec/family-behaviors.md) §6 (Claude Code only)**: for a human on Claude Code with the visualize tool present on an explicit invocation, build the **gaps widget** from the kit — call `mcp__visualize__read_me` once, then emit via `mcp__visualize__show_widget` an **HTML stall board** (per [`orient-contract.md`](references/orient-spec/orient-contract.md) §2 "gaps = a stall board / sieve — the hole is the deliverable"): a **4-lane grid** (blocked · open-forks · loose-ends · silent-gaps), each item carrying a muted **effort `S`/`M`/`L`** tag, **empty lanes shown as `— clear`** (the honest-negative, never omitted), the **"you are here" breadcrumb on top** (`↳ in: {parent_subject}`, omitted when absent), `◆◐◌` tier glyphs as redundant **non-color** encoding, and the legend `◆ attested · ◐ inferred · ◌ guessed · effort S·M·L · — honest-negative`. HTML chrome: colors only via CSS vars (no hardcoded hex), no `position:fixed`, and a visually-hidden `<h2 class="sr-only">` one-sentence summary for a11y. An **agent** consumer gets the YON record only; any **other runtime / no tool / indeterminate `handler_type`** gets the ASCII twin (fail-closed). The **information-complete ASCII stall-board twin is emitted when the selected face includes a visual** — it is the only render in a no-SVG channel and carries every lane item the widget does. Token discipline: a clean result collapses to one line. The footer is one evidence-derived line — and **only ever suggests a skill that is actually installed** (a `blockers_present` reason_code routes to `/plan-create`; an `unwritten_decision` routes OUT to an installed durable-capture skill per the family handoff-feeder).
    
    ## Record emission (the YON face — AGENT consumers only; never printed to a human)
    
    Before emission, pipe the actual current record in memory to
    `node <skill-dir>/references/tools/orient-validate.mjs -`. Do not save a derived
    record or substitute an example/self-test pass. The helper covers mapped enums,
    core/schema-version fields, parsing/duplicates, provenance syntax and barren
    status, with an ETA point warning; all other emitter obligations still apply.
    Select the consumer face before applying visual/trailer requirements: agent
    record-only, automator no visual, nominal human auto-loop one line, explicit
    human full face, unknown consumer ASCII fallback; preserve the widget escape.
    
    The structured face is the `gaps` slice of [`references/orient-spec/orient-record.yon`](references/orient-spec/orient-record.yon) (`schema_version = orient-record/1`). **Reserved tags only** — custom tags are parser-rejected. **List fields (`blocked_on_me`, `blocked_on_other`, `open_forks`, `loose_ends`, `silent_gaps`, `audit_mismatches`, `gamed_signals`) go in a sidecar `@MAP`, never an in-set bracket-list** (an in-set bracket-list corrupts the record *silently and still validates*). **Never run `yon format` on an emitted instance** — `CANON` mode is destructive on set-internal lists. Validate with `--profile exec`. Minimal skeleton:
    
    ```
    @CFG id=orient | set=[schema_version=orient-record/1,computed_at:ts=…,ephemeral:bool=true,tool=orient-gaps,tier=orient,scope=…,evidence_mode=git-only,gate_status=stalled,gate_blocking_field=loose_ends,gate_confidence_floor=git-attested,family_used=orient-gaps,family_suggested_next=plan-create,family_reason_code=blockers_present,overall_trust=med,degraded:bool=false]
    @CFG id=subject | set=[name=…,kind=monorepo,purpose=…,purpose_source=readme,intent_status=stated,parent_subject=…]   # parent_subject drives the ↳ in: breadcrumb; omit the field (and the breadcrumb) when absent
    @CFG id=gaps | set=[stall_status=stalled]
    @MAP name=blocked_on_me | pairs=["b1"->"…"]
    @MAP name=open_forks | pairs=["f1"->"…"]
    @MAP name=loose_ends | pairs=["l1"->"…"]
    @MAP name=silent_gaps | pairs=["s1"->"… (inferred)"]
    @MAP name=audit_mismatches | pairs=["a1"->"…"]   # --audit mode only
    @MAP name=gamed_signals | pairs=["g1"->"… ◌"]      # --audit mode only
    @MAP name=provenance | pairs=["gaps.loose_ends"->"git-attested:high:git-status"]
    ```
    
    A full worked instance ships at [`references/orient-spec/examples/orient-record.example.yon`](references/orient-spec/examples/orient-record.example.yon).
    
    ## Output — worked examples (markdown face)
    
    **Rich tier (a repo with real stalls — the ASCII stall-board twin):**
    ```
    🧭 open-skills — public skills repo.   ↳ in: open-source push   [identity: ◆ git]
    ## Stuck — 1 blocker · 1 open fork · 2 loose ends         ◆ git + plan
    ┌─ blocked ──────────────┬─ open-forks ───────────────┐
    │ ◐ P4 awaiting cold-vet [M] │ ◐ schema_version bump  [S] │
    ├─ loose-ends ───────────┼─ silent-gaps ──────────────┤
    │ ◆ 3 uncommitted, 1 untracked [L] │ ◐ no honesty fixture yet [M] │
    └────────────────────────┴────────────────────────────┘
    **→ Next:** clear the blocker, then commit the loose ends.
    Trust: ◆◐ · ⚠️ lean here: the blocker + fork are inferred (plan TODO / no record); only the loose ends are git-attested · next → /plan-create
    legend: ◆ attested · ◐ inferred · ◌ guessed · effort S·M·L · — clear (honest-negative)
    ```
    
    **Clean tier (nothing stuck — the success collapse; the widget shows every lane `— clear`):**
    ```
    🧭 some-cli — a git repo on `main`, clean tree.           [identity: ◆ git]
    **Nothing stuck — clean.** blocked: — clear · open-forks: — clear · loose-ends: — clear   ◆ git
    **Silent gaps:** none surfaced (coarse — git + plan only).  ◐ honest negative
    Trust: ◆ · [no observed blocker in checked inputs]
    ```
    
    **`--audit` tier (don't trust the orientation):**
    ```
    🧭 some-repo — a git repo on `wip`.                       [identity: ◆ git]
    ## Audit — 1 claim unbacked · 1 gamed signal              ◆ git
    | audit flag      | what                            | from         |
    | claim vs evidence | "tests pass" — no test files   | ◌ no evidence |
    | gamed signal    | 9 commits, 7 whitespace-only    | ◌ hollow ◌    |
    **→ Next:** back the test claim or drop it.
    Trust: ◌ · ⚠️ lean here: the "tests pass" claim has zero corroborating evidence.  [limited evidence]
    ```
    
    The ASCII stall board + the trust trailer with the `⚠️ lean your scrutiny here` line (naming the load-bearing guess) is **mandatory** on the selected full human face; the silent-gaps honest-negative is never silently dropped.
    
    ## Boundaries
    
    - **Not `/orient-status`** — that reports *position + remaining + ETA* (where you stand); orient-gaps reports *what's stuck and missing* (why you can't trust it / can't move).
    - **Not `/orient-map`** — that reports *shape + delta* (how you got here); orient-gaps reports the *stall surface* (what's blocking). They share one sweep's evidence, and orient-gaps **consumes** orient-map's topology (`on_branch`/`fork`/open-fork detection) rather than recomputing it.
    - **Not `/investigate`** — that gathers arbitrary deep facts read-only; orient-gaps computes a fixed *stall + silent-gap + audit* surface about ongoing work.
    - **Not `/reflect`, not `insight-*`** — those THINK / DECIDE; orient-gaps only SEES and reports NOW. After it, reach for `/plan-create` to clear the blockers, or the family handoff-feeder — an installed durable-capture skill — for an unwritten decision.
    - **Read-only.** It never mutates state; the one sanctioned reference point (an intent line) is caller-supplied or harness-held, never written to disk by default.
    
    ## Rules
    
    - MUST compute **two tiers from one sweep** — the stall surface (blockers / forks / loose ends) and the silent gaps; `--audit` raises the third (claim-vs-evidence + gamed-signal).
    - MUST emit `silent_gaps` (the honest negative) explicitly — never silently omit it — and mark each `◐`/`◌`, never as a confirmed fact.
    - MUST attribute `blocked_on_me` vs `blocked_on_other` **from evidence**, never assume; an empty stall surface collapses to a one-line success state, not a failure.
    - MUST take `intent` as input and gate goal-relative gaps when it's absent — never fabricate a goal or invent gaps off it.
    - MUST tag every field with a provenance tier and **fail closed** — `gate_status` = `degraded`/`indeterminate` with a sentinel — on zero evidence.
    - `--audit` MUST tier-tag a gamed signal `◌` so a hollow metric reads as hollow (the anti-Goodhart disclosure).
    - MUST, **when the consumer is an agent (`handler_type = agent`)**, emit a record conformant to `references/orient-spec/orient-record.yon` (reserved tags; list fields as sidecar `@MAP`; never `yon format` an instance). **A human consumer gets its selected plain-language face (one line when nominal, otherwise the read plus visual) — never the record, a raw record field, a node-id, or a gate enum.**
    - MUST, when the selected face includes a visual, emit the ASCII stall board + the trust trailer with the `⚠️ lean here` load-bearing-guess line; the visual's ASCII twin is mandatory.
    - MUST carry the **"you are here" breadcrumb** (`↳ in: {parent_subject}`) on the identity banner in both faces when `subject.parent_subject` is present — and **omit it entirely when absent** (never fabricate a parent); per `orient-contract.md` §1 and `family-behaviors.md` §8.
    - MUST NOT print the YON record — or any raw record field, node-id, gate enum, `@CFG` line, or `@MAP` line — into a human-facing reply. The record is the **agent** face (`handler_type = agent`); the human face is the plain-language read plus the visual (widget when available, ASCII twin otherwise). Per `references/orient-spec/orient-contract.md` §1 (token discipline) and `family-behaviors.md` §6.
    - MUST render the visual face per the render-face contract (Claude Code only, via `mcp__visualize__show_widget`): **agent → YON record only**; **human + Claude + tool + explicit invocation → stall-board widget + ASCII twin**; **other runtime / no tool / indeterminate `handler_type` → ASCII twin (fail-closed)**. The gaps widget is an **HTML stall board** — a 4-lane grid (blocked · open-forks · loose-ends · silent-gaps), each item a muted **effort `S`/`M`/`L`** tag, **empty lanes `— clear`** (honest-negative, never omitted), the breadcrumb on top.
    - MUST keep the widget and ASCII twin projections of **one node-structure** (same lane items + `◆◐◌` tier glyphs as redundant **non-color** encoding), HTML-chrome-compliant (colors only via CSS vars — no hardcoded hex; no `position:fixed`; a visually-hidden `<h2 class="sr-only">` summary for a11y), legend `◆ attested · ◐ inferred · ◌ guessed · effort S·M·L · — honest-negative`, **checked by the repository-only `tools/orient-roundtrip.mjs` release guard when running from a clone; installed copies retain this as an emitter obligation**. The widget MUST be **sparse — no per-node prose**.
    - MUST delegate gathering to a bounded, read-only, depth-1 subagent and return **only** the bundle (no raw search noise), with a re-runnable proof on every attested gap.
    - The family footer MUST only suggest an **installed** skill.
    
    > **Next skills.** On completion, run the Next Skills protocol (`next-skills/SKILL.md`): surface the `next-skills` recommendations from front-matter for the caller to pick. Offer only — never auto-invoke.
    
    > **Self-improvement.** On completion, run the Self-Improvement Protocol (`self-improve/SKILL.md`): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.