Explore `!` shell interpolation to pre-gather context and reduce token usage in commands

[LeanAndMean]

Summary

mach10 commands currently instruct Claude to run gh/git context-gathering commands as explicit in-session steps. Each such gather costs a full tool-call round trip (tool-call block + tool-result framing + inter-step reasoning). Claude Code supports !-backtick shell interpolation in command Markdown, which runs commands at invocation time and injects their output directly into the prompt -- collapsing that scaffolding into plain text. This issue is to explore adopting that pattern where it pays off, with a failure-recovery structure so a broken user setup (e.g., gh not installed/authenticated) remains diagnosable.

Current Behavior

Commands gather context through Claude-driven steps. For example, the opening of issue-plan, issue-implement, issue-assessment, issue-plan-review, pr-create, and doc-review runs the gh ... view + gh ... view --comments two-call pattern as instructions Claude executes one at a time, each incurring round-trip token overhead.

Proposed Behavior

• Investigate converting unconditional, independent, fast, read-only context gathers to ! interpolation in the relevant command files, so the output is injected at invocation rather than fetched via tool calls.
• Adopt a self-describing failure-recovery convention for each interpolated block so that when a command fails on a user's machine, Claude can still recover:
  • Restate the exact command as literal adjacent prose (it is not executed, so it survives even when the executed twin errors).
  • Capture stderr (2>&1) and append a detectable sentinel (e.g., || echo "__FAILED__") so failures are deterministically identifiable.
  • Provide a recovery instruction block (or a gather "manifest") that tells Claude how to interpret a failed/empty block and what the fallback is per gather.
• For commands with optional flags (e.g., pr-review-fix's --review-comment/--assessment-comment IDs), evaluate a guarded-block variant that injects the targeted fetch only when the flag is present and otherwise emits a sentinel handing the heuristic-selection path back to Claude -- avoiding a large unconditional comment dump.
• Document the decision (adopt / partially adopt / reject) and, if adopted, the conventions in CLAUDE.md under the command-writing guidance.

Acceptance Criteria

• A written assessment exists identifying which command gathers are good ! candidates (unconditional/independent/fast/read-only) versus which must stay Claude-driven (conditional, data-dependent on prior output, or requiring selection reasoning).
• The assessment covers the interaction with existing mach10 conventions, specifically: the task-tracking 1-to-1 step-visibility philosophy (pre-running collapses visible checkpoints into invisible preamble) and allowed-tools least-privilege gating (each interpolated command must be permitted or its block is silently skipped).
• A reusable failure-recovery convention (label + 2>&1 + sentinel + recovery instructions/manifest) is specified.
• At least one pilot conversion is prototyped (recommended: issue-assessment, as its opening gather is unconditional with no branching) so the token/diff tradeoff can be evaluated against the current flow before any broad rollout.
• The $ARGUMENTS escaping hazard (text substitution into the shell before execution) is documented as a caveat, with guidance to prefer positional $1 extraction and defensive parsing where free-text context could reach a ! block.
• A go/no-go recommendation for broader rollout (the six --comments two-call commands) is recorded.

Technical Notes

• Relevant convention anchors in CLAUDE.md: the --comments two-call sync (six command files), the Task Tracking section (Step 0 bootstrap, 1-to-1 step mapping), and the command-writing allowed-tools least-privilege guidance.
• ! interpolation can reference $ARGUMENTS/$1 (substituted before bash runs), so user-provided IDs are available to interpolation -- this is distinct from data that depends on a prior command's runtime output, which cannot be pre-run.
• Guarded-block sketch for optional flags: extract the ID with grep -oP, then [ -n "$id" ] && gh api .../comments/$id 2>&1 || echo "__NO_FLAG__ ...".
• Pre-run blocks run synchronously before the prompt reaches Claude; slow or hanging commands stall invocation with no spinner, so keep gathers fast and never place mutating/destructive commands in them.

[LeanAndMean]

Independent Assessment

This is an independent assessment performed via /mach10:issue-assessment. The issue is well-framed as a spike with "reject" pre-authorized as a valid outcome -- these notes sharpen the evaluation criteria rather than presuppose the result.

Verified !-interpolation semantics (load-bearing, currently unstated in the issue)

Three facts from the Claude Code docs change the analysis:

1. allowed-tools is not a hard gate. It grants no-prompt permission while a skill/command is active; it "does not restrict which tools are available... permission settings still govern." So the "block silently skipped if Bash absent" concern is misframed. Better: there is a clean policy sentinel already -- disableSkillShellExecution replaces each block with the literal text [shell command execution disabled by policy], which the recovery convention can detect directly.
2. Output is not re-scanned. "Substitution runs once... inserted as plain text and is not re-scanned for further placeholders." Recursive injection (an issue body smuggling a ! placeholder or <!-- mach10-plan --> marker that re-executes) is therefore impossible by design. Prompt-structure confusion from injected ## Step headings remains a lesser, real concern.
3. $ARGUMENTS is a pre-shell text substitution. This confirms and sharpens the escaping hazard: the suggested $1 positional extraction does not apply, because commands receive $ARGUMENTS as one combined free-text string, not word-split positionals. Any candidate block must depend only on a hardened/sanitized numeric ID and must never interpolate raw $ARGUMENTS (real context strings like "108 ignore the coverage check, focus on the unit test failures" would reach the shell verbatim).

Central decision axis: step visibility vs. token thrift

The strongest pushback is architectural. The Task Tracking guidance states the task list exists to make "every check visible" and mandates 1-to-1 step mapping ("Do not collapse multiple steps into compound tasks, even if some steps are brief"). The README frames context management purely as a session-boundary strategy, never within-session compression -- and the word "token" appears nowhere in CLAUDE.md, README.md, or any command. Pre-gathering turns the first visible step of nearly every tracked command into invisible preamble, optimizing a value the project has never claimed at the cost of one it repeatedly asserts. This tension deserves to be the spike primary evaluation axis, not an acceptance-criterion sub-bullet.

Token-increase risk on early-exit paths

Unconditional pre-injection fires the gather even when the command aborts before needing it -- a net increase on those paths:

• issue-plan-review stops immediately if no plan marker exists (Step 1), yet would have dumped issue + all comments first.
• issue-implement Step 2 has several terminal exits (dirty tree, no branch, diverged, cancel) before the Step 3 gather.
• pr-ci-fix exits if CI is green, yet would have dumped gh pr view --comments first.

This means the six --comments commands are not a uniform candidate set.

Refined candidate filter

A gather is a safe ! candidate only if it is: pure read-only (never gh pr checkout or any mutating call), keyed on a sanitized numeric ID (never raw $ARGUMENTS), not preceded by an early-exit branch, and -- ideally -- in a non-tracked command (to avoid the visibility cost). Under that filter, issue-assessment Step 2 remains the cleanest pilot; most of the rest fail one or more criteria.

Recommendation

Likely conclusion: reject for tracked commands; at most narrowly adopt for one or two pure, unconditional, non-tracked read-only gathers, behind an ID-sanitization + sentinel-recovery convention. Suggest treating the six-command rollout as out-of-scope for this spike -- its value is a documented decision plus conventions, not a broad conversion. Also worth noting any rollout would ripple through several CLAUDE.md sync rules (--comments two-call, Step 0 task-count tables, plan-marker, Step N.M sub-task numbering).

[LeanAndMean]

Addendum: due-diligence enforcement is the stronger motivation

A correction to the framing above. I centered the tradeoff on visibility vs. token economy, but the more important axis is enforced due diligence, and it favors interpolation:

• The Claude-driven model relies on Claude choosing to run each gather. A step like "read all comments" is a real skip-risk under context pressure or misjudged relevance. ! interpolation removes that discretion -- the evidence is in the prompt before reasoning starts and cannot be skipped.
• This ties directly to the existing Due-Diligence Steps convention (evaluation must trace to a gather, or output goes shallow/hallucinated). Interpolation enforces that guarantee structurally, which prose instructions do not. The --comments two-call sync exists for the same reason: comments carry load-bearing prior decisions.
• Visibility and enforcement are reconcilable: interpolate the gather to guarantee the evidence, but keep a visible task checkpoint ("review the pre-loaded context") so the task list retains a checkpoint. You lose the fetch checkpoint, not the review one.

Revised read: the strongest case for adopting is guaranteed evidence-gathering (a correctness property the methodology already values), not token savings (path-dependent, negative on early-exit paths). The spike should weight reliability as the primary benefit, with token impact secondary.