implicit-token-savings

implicit-token-savings

Choose the smallest sufficient local shell command for the real question.

Prefer compact output when it answers the question, especially when requested. Go directly to a known file, relevant diff, or full output when the task needs it; preliminary summaries are not prerequisites.

Decision Tree

What do you need right now?

• Repo shape, top-level files, or candidate paths

  • Start with ls -1, tree -L 2, or rg --files
  • Read references/filesystem.md

• A specific symbol, literal, stack trace, or TODO

  • Start with rg -n
  • Read references/filesystem.md

• A file excerpt or line range

  • Prefer the harness's targeted read tool if one exists
  • Otherwise use sed -n 'start,endp' file, head -n 80, or tail -n 80
  • Read references/filesystem.md

• Working tree state, scope of change, or recent history

  • Start with git status --short, git diff --stat, git diff --name-only, or git log --oneline
  • Read references/git.md

• Staging, committing, or pushing

  • Stage only the intended paths
  • Review all staged changes before an authorized commit; use summaries for scope and hunks for semantics
  • Only when pushing is authorized, use HEAD if the intended remote and destination are known
  • Read references/git.md

• Test, lint, or container health for a specific stack

  • Start with the narrowest stack-native command that exists: cargo test, npm test, ruff check, pytest, go test, or docker ps
  • Read references/runners.md

• The preferred command is missing

  • Follow the fallback matrix
  • Read references/patterns.md

Default Operating Rules

1. Use known context to choose a sufficient command directly. Inventory helps when paths are unknown, not when the target file is already named.
2. Keep scope explicit. Use --files, --name-only, or --stat for scope questions, and content output for semantic questions.
3. Use rg to locate unknown files or matching lines; read known relevant files without a search ceremony.
4. Use a path-specific git diff directly when reviewing behavior. Summaries help size or file-list questions but cannot establish semantics.
5. Use focused tests for local feedback, and run all repository-required validation gates before handoff. Narrow tests do not replace required full suites.
6. Prefer machine-readable output when another tool or script will consume it: --json, --format '{{json .}}', jq -r.
7. Choose terse, structured, or full output to match the known need. Preserve errors, exit status, and failure details; never compress away evidence needed for a safe decision.
8. If a preferred tool is absent, use the nearest cheaper equivalent rather than stalling.

Quick Reference

Choose a row for the question at hand; alternatives are not a required sequence.

Need	Compact option	Alternative when useful	Why
Top-level repo inventory	ls -1	ls -lah or tree -L 2	File names beat decorative output when you just need bearings
Directory shape	tree -L 2 path/	tree -a -L 3 path/	Depth caps keep structure readable
Candidate paths only	rg --files path/	rg --files path/ | rg 'pattern'	Avoid opening file contents at all
Text or symbol search	rg -n -F 'needle' path/	rg -n 'regex' path/	Choose literal or pattern semantics
File excerpt	sed -n '1,80p' file	Full read when whole-file context is needed	Pull enough context in one useful read
Working tree state	git status --short --branch	git status	Short form is enough for most decisions
Change scope or semantics	git diff --stat	git diff --name-only for paths; git diff -- path for semantics	Choose the detail the question requires
Recent history	git log --oneline --decorate -n 15	git log --stat -- path	Commit headlines answer many questions quickly
Stage and review	git add -- path && git diff --cached --stat	git diff --cached -- path	Review only what you are about to commit
Authorized push of current branch	git push -u origin HEAD	Inspect the destination if unknown	HEAD is shorthand, not push authorization
Node test surface	npm test -- <runner-args>	npm test -- --help if flags are unknown	Use the project's known runner contract
Rust test surface	cargo test name -- --nocapture	cargo test package::module::name	Choose a test filter for focused feedback
Python lint surface	ruff check path/	ruff check path/ --fix	Keep fixes explicit
Python test surface	pytest -q tests/test_file.py -k expr	pytest -q tests/	Choose focused feedback or suite coverage as needed
Go test surface	go test ./pkg/... -run Pattern	go test ./...	Package and -run filters cut noise
Container inventory	docker ps --format '{{json .}}'	docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'	Structured rows are easier to filter or summarize

Reading Guide

Task	Read
Repo shape, search, and targeted file reads	references/filesystem.md
Compact git status, diff, history, staging, and push patterns	references/git.md
Narrow test, lint, and container commands	references/runners.md
Context-driven command choices and fallbacks	references/patterns.md
Missing results, over-compression mistakes, and command traps	references/gotchas.md

Gotchas

1. rg respects ignore rules. Missing results usually need --hidden, -u, or --debug, not a tool switch.
2. tree is for shape, not truth. Cap depth early or you will spend tokens on directory art.
3. sed -n is cheaper than cat when you need a slice, but repeated slicing can cost more than one full read once you know the exact short file you need.
4. git diff --stat hides semantics. Escalate to a path-specific diff before drawing conclusions about behavior.
5. npm test forwards extra runner flags only after --.
6. docker ps can succeed while the container you care about is unhealthy. Read Status, not just presence.
7. git add . is the opposite of token discipline when only one file matters. Stage explicit paths.

Helper Scripts

• scripts/probe_implicit_token_savings.py detects available tools and verifies compact command behavior on temporary local fixtures.
• scripts/validate.py checks packaging, required files, and syntax.
• scripts/test_skill.py runs validation, eval coverage checks, cross-reference checks, and the probe suite.
• templates/session-checklist.md is a reusable checklist for starting a low-noise coding session.

When Guidance Stops Helping

If a compact command fails or hides needed evidence, use fuller output and inspect installed help or official version-matched docs. Preserve failures and unknowns rather than optimizing them away. Propose a canonical skill update when an example is stale or saves less work than it adds, citing the tool/version and a reproducer. Do not silently edit installed copies or publish the proposal.