<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->

# Context-Efficient Tool Output

RTK reduces context load for noisy terminal summaries. It is an efficiency layer,
not an evidence boundary: capability, correctness, and exact output take priority
over token savings.

## Default workflow

1. **Start narrow** with `rtk-helper.sh` for supported summary commands:
   - `rtk-helper.sh git status`
   - `rtk-helper.sh git log --oneline -20`
   - `rtk-helper.sh gh pr list --repo owner/repo --limit N`
   - `rtk-helper.sh gh issue list --repo owner/repo --limit N`
   - In interactive discovery, use these RTK forms instead of raw `gh pr list`
     or `gh issue list` unless the command needs structured/exact output.
   - RTK v0.41.0 also adds upstream Gradle wrapper support, `rtk init --agent hermes`, `rtk init --dry-run`, `transparent_prefixes` for wrapper command passthrough, tee tail hints, Docker Compose log tail forwarding, compact Kubernetes pod/service summaries, and git push/status filtering fixes; prefer those upstream features over custom aidevops shims when integrating supported runtimes, build tools, or noisy terminal summaries.
2. **Assess sufficiency**: proceed only if the filtered output contains every
   fact needed for the next decision.
3. **Broaden immediately** when output is incomplete, ambiguous, expanded rather
   than reduced, or exact evidence is needed:
   - rerun the raw/direct command;
   - use a narrower raw command with explicit fields;
   - read exact files with the Read tool;
   - request logs/check output directly for terminal failures.

## Diagnostics workflow

When RTK output seems misleading, too large, too small, or insufficient for a
decision, record a comparison before changing guidance:

```bash
rtk-helper.sh --compare gh pr list --repo owner/repo --limit 10
```

The comparison reports raw vs RTK-filtered exit codes, bytes, approximate token
counts, line counts, and a first-pass recommendation. It intentionally omits the
command output to avoid copying noisy or sensitive data into diagnostics. Rerun
the raw command directly when exact evidence is needed.

To verify adoption in recent OpenCode sessions, run:

```bash
rtk-helper.sh --adoption-report
```

The report counts sessions, Bash tool calls, RTK helper calls, raw eligible list
commands that should have started through RTK, and structured/exact list commands
that correctly bypass RTK.

For pulse/GitHub API-budget symptoms, start with the compact, sanitized local
summary before reading long logs or running more `gh` calls:

```bash
pulse-diagnose-helper.sh api-budget
pulse-current-state-helper.sh --window 15m --json
```

Then broaden only when the summary cannot prove whether the path is REST-first
or GraphQL-only, whether shared cache priming exists, or whether `gh_pr_view`
misses are duplicate same-PR misses rather than unique PR reads. Do not broaden
`gh_pr_view` cache semantics before that hit/miss evidence exists.

Use comparison results to classify a command:

- **Good first-pass RTK candidate**: exit codes match, output shrinks, and the
  summary preserves all facts needed for the next decision.
- **Raw or narrower command preferred**: output expands, output is unchanged, or
  structured fields can answer the question more precisely.
- **Unsafe for RTK**: exit codes differ, omitted lines could alter diagnosis, or
  exact evidence/security/JSON/diff semantics are required.
- `git status` expansion is a regression signal: RTK v0.41.0 dropped the
  compact-status `-uall` flag, so tracked-file paths remain visible while
  untracked directories stay summarized as they appear in raw
  `git status --short` output. Rerun raw status and verify RTK version when
  comparison shows expansion; older RTK versions still use the noisier
  compact-status behavior.

## Always bypass RTK

- File reads and source inspection.
- JSON used for assertions, parsing, or automation decisions.
- Exact/verbatim diffs, patches, or blame output.
- Security scans, credential-sensitive output, or prompt-injection checks.
- Terminal failures where omitted lines could change diagnosis.
- Any command whose output must be cited byte-for-byte in an issue, PR, review,
  or audit trail.

## Validation notes

Initial validation for GH#23212 found RTK useful for list-style GitHub context
(`gh issue list`, `gh pr list`) and only situational for tiny `git status`,
already compact `git log --oneline`, or full issue bodies. The v0.41.0 release
fixes the compact-status expansion regression, preserves full status paths, and
streams git push output to avoid spurious timeout symptoms. Prefer RTK for
discovery and triage summaries; prefer raw output or structured fields for exact
task briefs.

For future regressions, capture:

1. the exact command;
2. `rtk-helper.sh --compare ...` output;
3. whether the RTK-filtered response was sufficient, required fallback, or was
   unsafe for RTK;
4. the raw command output only when it is safe and necessary to prove the issue.
