codex-token-discipline

Codex Token Discipline

Purpose

Reduce total root-and-child cost without weakening task success, required evidence, or the requested deliverable.

Keep reads, tool output, retries, and delegation bounded. Preserve reusable evidence and escalate only the unresolved part.

Operating Frame

Use only what changes behavior:

1. Name the current phase: explore, plan, implement, verify, publish, or handoff.
2. Define the next evidence needed before reading broadly.
3. Before a potentially noisy tool call, define the smallest useful return shape and output budget.
4. Delegate noisy side work only when it can return distilled findings with evidence.
5. At phase boundaries, save compact resume state and hand session-continuation decisions to the owning director when one exists.

Skip the ritual for small edits, direct answers, and simple commands.

Preflight Output Contract

Prevent excess output before it enters the main context; do not rely on summarizing it afterward.

• For any unpredictable or batch command, name the required return shape first: status, count, paths, selected fields, or first actionable failure.
• Set a finite return budget on the tool call. For exec-family calls, default to an explicit budget at or below 2,000 tokens unless named evidence requires more; do not wait for a single large-output threshold.
• Filter, aggregate, or select at the source. For tests and builds, return the exit status, first actionable failure, and command before requesting more detail.
• When full output is useful for later inspection, write it to a task-local or temporary artifact and return only its path, size, compact summary, and first actionable failure. Inspect bounded slices from the artifact as needed.
• Do not create an artifact for disposable output that can be reduced at the source.

Summary-First Reads

Start narrow; widen only when it changes the next decision.

• Search with rg or file lists before opening files.
• Prefer git diff --stat, git diff --name-only, focused git diff -- <path>, and targeted sed -n ranges before full diffs.
• For logs and command output, use tail, head, jq, counts, filters, or error searches before full transcripts.
• Treat every returned tool result as future input cost. Prefer counts, paths, summaries, or selected evidence before full output.
• After a failure, widen from the saved artifact or rerun only the smallest failing scope; avoid repeated full transcripts in the main thread.