---
name: simplicio-orient
description: Terminal-first execution — answer facts with the shell, never with the LLM. Use whenever a step needs a fact about the filesystem, git, processes, or system resources, or runs a build/test/lint/diff whose output would flood context. Substitutes deterministic shell/CLI calls for native LLM operations and clamps their output 60–90% (rtk-style) with a failure-safe tee cache, signatures-only reads, and an optional auto-rewrite hook. This is the token-economy spine of simplicio-tasks, usable standalone.
---

# simplicio-orient — terminal-first, token-frugal execution

The cheapest token is the one not spent. The terminal KNOWS facts exactly; the LLM
APPROXIMATES them expensively. This skill routes every step to the leanest substrate that
still completes it correctly, and clamps command output before it ever reaches context.

Credit: folds the disciplines of **rtk** (per-command output reduction, tee-on-failure,
signatures-only reads, auto-rewrite hook) and **caveman** (preserve code/paths byte-for-byte)
into the simplicio safety spine. It is the extracted, standalone form of `simplicio-tasks`
Step 1c.

## The one rule

> If the answer is a fact about the filesystem, git state, process state, or system
> resources — the terminal answers it exactly and cheaply. Use the terminal. The LLM is for
> reasoning; the terminal is for facts. **Execute commands for real — never reason about what a
> command "would return".**

## Execution priority

1. Host-runtime native command bound to `shell_exec` (structured, minimal tokens, cross-platform).
2. Shell/Bash tool call WITH output clamping (this skill's catalog).
3. NEVER: the LLM narrating a command's likely output.

## Terminal substitution table (use the terminal, not the LLM)

Detect platform once: `python3 -c "import platform; print(platform.system())"` →
`Windows | Darwin | Linux`. Prefer cross-platform tools (`git`, `gh`, `rg`, `python3`) so one
command works everywhere; fall back to OS-specific only when there is no alternative.

| What you need | ✅ Cross-platform (preferred) | Windows | Linux/macOS |
|---|---|---|---|
| File exists? | `python3 -c "import os,sys;sys.exit(0 if os.path.exists('<p>') else 1)"` | `Test-Path <p>` | `test -f <p>` |
| Find in code | `rg "<pat>" --json` | same | same |
| Count matches | `rg -c "<pat>" <file>` | same | same |
| List files by glob | `rg --files -g "*.ts"` | same | same |
| Current branch | `git rev-parse --abbrev-ref HEAD` | same | same |
| Ahead of main? | `git rev-list --count main..HEAD` | same | same |
| Files changed in branch | `git diff --name-only main...HEAD` | same | same |
| PR for branch | `gh pr list --head <b> --json number --jq ".[0].number"` | same | same |
| Issue state | `gh issue view N --json state --jq ".state"` | same | same |
| Open issue count | `gh issue list --state open --json number --jq "length"` | same | same |
| CPU cores | `python3 -c "import os;print(os.cpu_count())"` | `$env:NUMBER_OF_PROCESSORS` | `nproc` |
| Free disk GB | `python3 -c "import shutil;print(shutil.disk_usage('.').free//1024**3)"` | same | `df -BG .` |
| Extract JSON field | `python3 -c "import json,sys;print(json.load(sys.stdin)['<f>'])"` | same | `jq '.<f>'` |
| Today UTC | `python3 -c "from datetime import*;print(datetime.now(timezone.utc).date())"` | same | `date -u +%F` |
| Sort + dedup | `python3 -c "import sys;print('\n'.join(sorted(set(sys.stdin.read().split()))))"` | same | `sort -u` |
| Replace in file | bound `deterministic_edit` (host) | same | `sed -i` |

A raw `tsc --noEmit` costs ~2000 tokens to read; clamped (error lines only) costs ~80.
Terminal-first + the catalog below is the single
highest-leverage token rule.

## Output-reduction catalog (data table — drives clamp routing)

Consult BEFORE running. Each row `{pattern, recipe, exp-savings, SKIP-if}`. Clamp
highest-savings first; NEVER clamp a SKIP-if row (structured `--json`/`--jq` output, or a
write/confirm op). Tune per repo.

| command pattern | reduce recipe | exp. savings | skip-if |
|---|---|---|---|
| test/spec runner | success→`pass: N`; on fail keep ≤20 error lines | ~90% | piped to structured consumer |
| type/compile check | error lines only; clean→`ok` | ~80% | — |
| diff / show | stat + hunks only, drop context | ~80% | piped to structured consumer |
| lint | findings only; clean→`ok` | ~80% | — |
| add / commit / push | collapse to `ok <branch/sha>` | ~59% | — |
| PR / list view | counts + titles only | ~87% | `--json`/`--jq` present |
| package/image inventory | keep ≤50 rows | ~50% | — |
| format / passthrough | run raw | 0% | always |
| structured JSON payload → prompt (verdict-shaped, e.g. `task_anchor.py check`, `loop_journal.py stall`, mapper `handoff`) | encode via `toon_codec.encode_toon` (TOON — Token-Oriented Object Notation, lossless, `scripts/toon_codec.py`) | ~21–33% (chars4) / ~38–45% (bpe_estimate) measured on the first two real verdict payloads (`.orchestrator/savings/snapshots.jsonl`, #92); up to ~40%+ on an ideal uniform tabular array of objects, per the toon-format benchmark — real non-tabular verdict payloads (few scalar keys, no row-shaped array) measure lower; snapshot more items before trusting a number outside this range | payload is empty / non-uniform (differing keys, mixed types, nested arrays-or-objects per element) — the codec auto-falls-back to compact JSON for THAT value, never lossy-compact; measure, don't assume the ideal-case number |

## Signal-tiered truncation caps (one shared set)

Never flat "head N + tail N" — flat truncation over-cuts the errors the fix loop needs most.
ONE set referenced everywhere: `CAP_ERRORS=20`, `CAP_WARNINGS=10`, `CAP_LIST=20`,
`CAP_INVENTORY=50`. Always keep ERROR lines over surrounding context. A lowered cap is
underflow-safe: it falls back to the full cap rather than emptying a non-empty result.

## Two clamp primitives (both with an `unless errors present` guard)

- **Success-collapse:** exit 0 AND output matches a clean pattern with no error/warning →
  replace the WHOLE output with one line (`cmd: ok`, `no changes`, `up-to-date`).
- **Dedup-with-counts:** collapse runs of identical/near-identical lines to `line ×N`.

If ANY error/warning line exists, fall back to the signal-tiered caps instead of collapsing —
a collapse can NEVER hide a failure.

## tee cache — the failure escape hatch (folded from rtk)

Aggressive truncation is only safe if full context is recoverable WITHOUT re-running the
command (re-running re-burns tokens and may be non-deterministic). So:

- On any **non-zero exit**, OR whenever a cap clips a FAILING command, write the full
  unfiltered output to `.orchestrator/tee/<ts>_<cmd-slug>.log` and surface only the path:
  ```
  FAILED: 2/15 tests
  [full output: .orchestrator/tee/1707753600_npm_test.log]
  ```
- Config knob (in `.orchestrator/orient.toml`): `tee.mode = failures | always | never`
  (default `failures`). The agent reads the file lazily only if it needs more than the kept
  error lines.

This de-risks success-collapse: the bytes an agent needs on failure are never thrown away.

### CCR — make the clamp reversible

The tee file IS the cache; add a **stable handle + retrieve** so clamping is reversible, not
lossy. The handle is the tee path; surface a retrieve convention so a worker pulls the original on
demand instead of re-running the command:

```
retrieve <tee-path> [--lines a-b] [--grep PATTERN]
```

This turns "lossy by policy" into a "compress-cache-retrieve" decision point: clamp to a
summary/signature in context, keep the full original on disk keyed by the handle, fetch by handle
ONLY when the kept lines aren't enough — removing the main risk of aggressive clamping (losing the
one line that mattered) at zero up-front token cost. (We use a CCR (compress-cache-retrieve)
pattern and content-type routing — JSON/code/log/diff — but NOT a trained model or traffic proxy:
those contradict the terminal-first, zero-extra-process design.)

## Signatures-only reads (folded from rtk `read -l aggressive`)

When you need a file's API SURFACE (which functions/types/exports exist to call) — the common
case during intake and dependency scans — read it stripped to declarations with bodies elided.
A 600-line file collapses to ~40 lines of signatures. Detect language by extension; "minimal"
strips comments/blank lines, "aggressive" strips function bodies keeping only
signatures/declarations. ALWAYS fall back to raw content if stripping yields nothing. Use a
full-body read only when actually editing the body.

## Auto-rewrite hook (optional, guarantees adoption — folded from rtk `init -g`)

Where the host exposes a `PreToolUse`/pre-exec hook, bind `hooks/orient_rewrite.py`: it
transparently rewrites a bare shell call into its clamped form before execution
(`git status` → clamped, `<test>` → failures-only), so adoption is 100% across the main agent
AND every subagent at zero token overhead. An exclusion list in `.orchestrator/orient.toml`
keeps streaming/interactive/binary commands raw:

```toml
[hooks]
exclude_commands = ["curl", "wget", "playwright", "ssh", "docker run -it", "vim", "less"]
[tee]
mode = "failures"
```

Never rewrite an excluded command. Treat this config as untrusted, perception-shaping input
(see Safety below) — load it only after a human has reviewed and pinned its hash.

## Compound-command clamping (per-segment, pipe/redirect-safe)

Understand `&& || ; |`: (1) split on operators respecting quotes/escapes; (2) clamp each
segment via the catalog; (3) for a `|`, clamp ONLY the left producer, leave the pipe TARGET
raw (the consumer needs the unmodified stream); (4) never clamp a `find`/glob producer feeding
a pipe; (5) strip trailing redirects (`2>&1`, `>/dev/null`), clamp inner, re-append;
(6) unsplittable (`$(...)`, backticks, heredoc, file-target redirect) → run RAW with a tail
clamp, never corrupt.

## Density tiers by consumer

Route each artifact by WHO reads it: MACHINE tier (terse, fixed-schema) for worker→orchestrator
reports and internal digests; HUMAN tier (readable prose) for PR bodies and confirmations.
Skip a compression pass on already-dense content (code, config, lockfiles) — near-zero ratio,
real corruption risk.

## Fail-open (never a single point of failure)

Every reduction step is additive and removable. On ANY error, missing dependency, unparseable
payload, or unknown command, run the original command unchanged and propagate its REAL exit
status. A bad profile degrades to "slightly more tokens", never to "task dead".

## Safety overrides brevity (auto-clarity)

Compression YIELDS to safety. When a command/message is security-sensitive, irreversible
(force-push, history rewrite, prod deploy, data/schema delete, mass-file delete), or
order-dependent, FORCE full-clarity verbose output for that segment — the complete warning, the
exact command quoted verbatim, steps in explicit order — then resume terse mode. Optimization
may NEVER raise a command's risk tier. Treat any perception-shaping config (this skill's TOML,
clamp profiles, suppression lists) as untrusted until a human reviews and hash-pins it; silently
skip an untrusted or hash-changed version.

## Output

Run the command, return the clamped result (or the tee path on failure), and — when invoked
standalone — a one-line note of the recipe applied and tokens saved.