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", "
Install
npx skills add https://github.com/allemaar/open-skills/tree/main/skills/orient-gaps
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
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@STAMPdate.
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.
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
intentargument if given. If intent can't be grounded, gate the goal-relative gaps (render— (needs goal), cap toguessed) and surface only the evidence-attested stalls (uncommitted files, unmerged branches). Never fabricate a goal and hang invented gaps off it.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/
@blockedmarkers, 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-runnablesource:line/git-ref proof.
- git tier → uncommitted/untracked files (
Compute two tiers (always):
- Stall surface —
blocked_on_mevsblocked_on_other(attribute from evidence, never assume),open_forks(unresolved decisions),loose_ends(uncommitted/untracked). Setstall_status = stalledwhen something blocks; otherwiseready. - 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
◐ inferredor◌ guessed; never present a silent gap as a confirmed fact.
- Stall surface —
--auditmode — 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 (seereferences/orient-spec/family-behaviors.md§4).
Tag every field with a provenance tier —
◆ git-attested·◐ inferred·◌ guessed— and fail closed: setgate_status(enum:ready | blocked | stalled | degraded | indeterminate) todegraded/indeterminatewith a sentinel — never a plausibleready— on barren evidence. An empty stall surface is a success state (collapse to one line: "nothing stuck — clean"), NOT a failure.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_meonce, then emit viamcp__visualize__show_widgetan HTML stall board (perorient-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 effortS/M/Ltag, 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), noposition: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 / indeterminatehandler_typegets 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 (ablockers_presentreason_code routes to/plan-create; anunwritten_decisionroutes 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, notinsight-*— those THINK / DECIDE; orient-gaps only SEES and reports NOW. After it, reach for/plan-createto 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;
--auditraises 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_mevsblocked_on_otherfrom evidence, never assume; an empty stall surface collapses to a one-line success state, not a failure. - MUST take
intentas 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/indeterminatewith a sentinel — on zero evidence. --auditMUST 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 toreferences/orient-spec/orient-record.yon(reserved tags; list fields as sidecar@MAP; neveryon formatan 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 hereload-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 whensubject.parent_subjectis present — and omit it entirely when absent (never fabricate a parent); perorient-contract.md§1 andfamily-behaviors.md§8. - MUST NOT print the YON record — or any raw record field, node-id, gate enum,
@CFGline, or@MAPline — 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). Perreferences/orient-spec/orient-contract.md§1 (token discipline) andfamily-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 / indeterminatehandler_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 effortS/M/Ltag, 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; noposition: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-onlytools/orient-roundtrip.mjsrelease 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 thenext-skillsrecommendations 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.
Reviews (0)
No reviews yet.
No comments yet.