⚡ Claude Token Optimization2026-06-06 — Documentation Maintainer

[github-actions]

Target Workflow: documentation-maintainer

Source report: #4426
Estimated cost per run: ~$0.22
Total tokens per run: ~323K (1 run in period)
Cache read rate: ~88% effective reuse (8.4× effective/raw ratio)
LLM turns: 6 (configured max-turns: 5 — overrun)
Model: claude-haiku-4-5

⚠️ 100% failure rate in the current period (1/1 runs failed). All 323K tokens were spent without producing a PR.
📉 Tokens dropped ~51% from the previous run (664K → 323K), showing prior improvements are working — but the run still fails.

Current Configuration

Setting	Value
Tools loaded	1: edit (bash: false, github: false)
Tools actually used	edit (file reads + writes)
Network groups	None
Pre-agent steps	Yes — builds context.md with git diffs + affected docs list
Prompt size	~2,400 chars (~600 tokens)
Git diff cap	head -100 lines (2 occurrences)
Affected docs cap	head -10 files (3 occurrences)
Max turns	5 (run used 6 turns)

The tool surface is already minimal. No network groups to trim. Optimization opportunities are in context scoping, turn reduction, and fixing the failure.

Recommendations

1. Investigate and Fix the Failure (100% failure rate)

Estimated savings: ~323K tokens/run on every failing run — currently 100% of cost is wasted

The run concluded failure with error_count: 1, turns: 6 against max-turns: 5, and temporary_id_map_status: missing (PR was never created). Zero value delivered per run.

Immediate fix — increase max-turns to allow task completion:

 engine:
   id: claude
   model: claude-haiku-4-5
-  max-turns: 5
+  max-turns: 8

The agent needs 6 turns to read up to 10 docs + make edits + output PR summary. Combined with Recommendation #2 (pre-loading docs), the turn count should fall to 3–4, making max-turns: 5 viable again.

Also check whether the error is the agent trying to call bash or github tools (both disabled). Add an explicit prohibition to the prompt:

"Do not attempt to use bash commands or GitHub tools — they are unavailable in this environment."

---

2. Pre-load Affected Documentation Content in Pre-Agent Steps

Estimated savings: ~100–150K tokens/run (~31–46%) — eliminates 2–3 read turns

Currently the agent reads doc files via the edit tool (read → plan → edit = 2 turns per doc). Moving doc content into context.md during pre-agent setup eliminates these read turns entirely.

Add after the Build documentation maintainer context step in .github/workflows/documentation-maintainer.md:

      - name: Pre-load affected documentation content
        run: |
          CONTEXT_DIR=/tmp/gh-aw/doc-maintainer-context
          AFFECTED="$CONTEXT_DIR/affected-docs.txt"

          if [ ! -s "$AFFECTED" ]; then
            echo "No affected docs to pre-load"
            exit 0
          fi

          {
            echo ""
            echo "## Affected Documentation Content (pre-loaded — do not re-read these files)"
            echo ""
            head -3 "$AFFECTED" | while read -r doc; do
              if [ -f "$doc" ]; then
                echo "### File: $doc"
                echo '```'
                head -200 "$doc"   # cap per-file size
                echo '```'
                echo ""
              fi
            done
          } >> "$CONTEXT_DIR/context.md"

          SIZE=$(wc -c < "$CONTEXT_DIR/context.md" | tr -d ' ')
          echo "Final context.md size: ${SIZE} bytes"

Update the agent prompt Step 2:

"The full content of up to 3 affected documentation files is pre-loaded in context.md under '## Affected Documentation Content'. Read from context.md directly — do not use the edit tool to re-read files before making edits."

---

3. Reduce Affected Docs Cap from 10 to 3

Estimated savings: ~35–70K tokens/run (~10–21%) — eliminates agent reading 7 unnecessary files

Change three head -10 → head -3 in the Build documentation maintainer context step:

-        done | grep -E '(^docs/.*\.md$|^[^/]+\.md$)' | sort -u | head -10 > "$AFFECTED" || true
+        done | grep -E '(^docs/.*\.md$|^[^/]+\.md$)' | sort -u | head -3 > "$AFFECTED" || true

-          grep -i -F -f "$TOKENS" "$DOC_POOL" | head -10 > "$AFFECTED" || true
+          grep -i -F -f "$TOKENS" "$DOC_POOL" | head -3 > "$AFFECTED" || true

-        head -10 "$DOC_POOL" > "$AFFECTED"
+        head -3 "$DOC_POOL" > "$AFFECTED"

---

4. Trim Git Diff Cap from 100 to 50 Lines

Estimated savings: ~15–30K tokens/run (~5–9%)

Change two head -100 → head -50 occurrences:

In check_relevant_changes job:

-          git log --since="7 days ago" ... | grep -v '^Binary' | head -100 > "$DIFF_PREVIEW"
+          git log --since="7 days ago" ... | grep -v '^Binary' | head -50 > "$DIFF_PREVIEW"

In Build documentation maintainer context step:

-      git log --since="7 days ago" ... | grep -v '^Binary' | head -100 > "$CONTEXT_DIR/recent-diffs.txt"
+      git log --since="7 days ago" ... | grep -v '^Binary' | head -50 > "$CONTEXT_DIR/recent-diffs.txt"

---

5. Add Markdown-Specific Skip Logic

Estimated savings: ~323K tokens/run (full skip) when only non-doc code changed

The current skip_agent check only skips on diffs < 100 bytes. Add a fast-exit when no markdown or docs files changed in the last 7 days:

           {
             echo "changed_count=$COUNT"
             echo "has_changes=$HAS_CHANGES"
             echo "skip_agent=$SKIP_AGENT"
           } >> "$GITHUB_OUTPUT"
+          MD_CHANGES=$(git log --since="7 days ago" --name-only --format="" -- '*.md' docs/ | grep -cE '.' || echo "0")
+          if [ "$HAS_CHANGES" = "true" ] && [ "$SKIP_AGENT" = "false" ] && [ "$MD_CHANGES" -eq 0 ]; then
+            echo "skip_agent=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::No markdown/docs changes in 7 days. Skipping documentation review."
+          fi

---

Cache Analysis (Anthropic-Specific)

Metric	Value
Raw tokens billed	323,282
Effective tokens (context window)	2,720,558
Cache reuse ratio	8.4×
Estimated cache reads	~2,397K tokens
Estimated per-turn avg (raw)	~53.9K tokens
Estimated per-turn avg (effective)	~453K tokens

The 8.4× reuse ratio is healthy — system prompt and context.md prefix are being cached and reused across all 6 turns. The high effective/raw ratio is driven by the growing conversation context: each time the agent reads a documentation file, its content joins the context window and is re-sent (from cache) on every subsequent turn.

Cache write amortization: With a 5-minute TTL and a 3.5-minute run, all Turn 1 cache writes are reused in Turns 2–6. This is working well. However, as the agent reads docs during turns, each read triggers a new cache write (the expanded context), compounding costs.

Key insight: Pre-loading docs into context.md (Rec #2) front-loads the cache write to Turn 1, giving Anthropic prefix caching the largest possible static prefix — maximizing cache read reuse and minimizing per-turn cache writes.

Expected Impact

Metric	Current	Projected	Savings
Total tokens/run	~323K	~140K	~57%
Cost/run	~$0.22	~$0.09	~59%
LLM turns	6	3–4	−2 to −3
Run duration	3.5 min	~2 min	~43%
Failure rate	100%	<25% (est.)	−75%

Projected figures assume all 5 recommendations are applied. Fixing the failure (Rec #1) alone is the highest-leverage single change.

Implementation Checklist

• Review run §27054269866 turn-by-turn logs to identify the exact error
• Increase max-turns from 5 → 8 (or reduce task scope via Rec Secret proxying #2 first, then try max-turns: 5 again)
• Add pre-load step for doc content to steps: in .github/workflows/documentation-maintainer.md (Rec Secret proxying #2)
• Update agent prompt Step 2 to reference pre-loaded content (Rec Secret proxying #2)
• Change head -10 → head -3 in 3 locations (Rec feat: add integration test for rostbuness #3)
• Change head -100 → head -50 in 2 locations (Rec fix: add missing Docker image pulls to robustness test workflow #4)
• Add markdown-specific skip logic to check_relevant_changes step (Rec mossaka/log filtering #5)
• Recompile: gh aw compile .github/workflows/documentation-maintainer.md
• Post-process: npx tsx scripts/ci/postprocess-smoke-workflows.ts
• Verify CI passes on PR
• Compare token usage on next run vs 323K baseline

Generated by Daily Claude Token Optimization Advisor · sonnet46 2.5M · ◷