[subagent-optimizer] Optimize developer-docs-consolidator — 2026-05-03

[github-actions]

Target Workflow

File: .github/workflows/developer-docs-consolidator.md
Engine: Claude Code
7-day token usage: ~4,465,843 tokens across 1 run (~4,465,843 avg/run)

Why This Workflow

The Developer Documentation Consolidator is the highest-token Claude Code workflow in the last 7 days with nearly 4.5 M tokens per run. It has 6 distinct phases (Phase 0–5), two of which — file discovery/cataloging and per-file tone classification — are purely extractive tasks that a smaller model can execute at full quality while returning compact summaries to the main agent, dramatically shrinking the main model's context.

---

Optimization — Inline Sub-Agents

LLM Expert Reasoning

• Phase 1 (Discovery & Inventory) scores 10/10: It reads N markdown files and emits a structured table — path, purpose, line count, status. Pure extraction, zero cross-file reasoning. Haiku handles this at parity with a larger model.
• Phase 2 (Tone & Consistency Analysis) scores 9/10: It classifies each sentence/paragraph as marketing vs. technical and checks formatting per file. This is a fixed-taxonomy binary classification — exactly the task where smaller models match larger ones.
• Parallelism opportunity: With sub-agents, tone analysis of each file can be fanned out concurrently rather than processed sequentially by the main agent.
• Main model freed: By offloading Phases 1–2 to Haiku, the main model never needs to hold all raw file content in context; it only sees the compact inventory table and structured issues JSON, saving the largest source of token volume.
• Phases 3–5 stay in main: Content adjustment (Mermaid generation), consolidation (cross-file synthesis), and reporting (holistic narrative) all require full context and judgment — these must remain with the main model.

Proposed Sub-Agents

1. file-cataloger (claude-haiku-4.5)

Extracted task: Discover and catalog all markdown files in specs/ and scratchpad/ with path, purpose, and line count.
Why haiku: Pure file-read and attribute extraction — no synthesis or cross-file reasoning required.
Score: 10/10 (independence: 3, haiku-adequacy: 3, parallelism: 2, size: 2)
Estimated savings: ~8% of main-model tokens/run (~357,000 tokens)

Agent definition (copy-paste ready)

## agent: `file-cataloger`
---
description: Discover and catalog markdown files in specs and scratchpad directories
model: claude-haiku-4.5
---
Find all `.md` files in the `specs` and `scratchpad/` directories using bash.
For each file found:
1. Read the file content
2. Identify its purpose from the first heading or opening paragraph
3. Count lines: `wc -l <file>`
4. Assign status: "To be analyzed"

Output a markdown table:
| File | Purpose | Lines | Status |
|------|---------|-------|--------|

One row per file. Purpose should be 5–10 words max.
Return only the table, no other commentary.

Invocation change in main prompt:

Before:

### 1. Identify All Markdown Files
Use `search` to discover relevant documentation and spec files before listing files with bash:
```bash
# Use search first to find semantically relevant files
# Example: search("developer instructions code organization")
# Then read the returned file paths to get full content

Find all .md files in the scratchpad/ directory:

find specs -name "*.md"

2. Read and Catalog Files

For each markdown file found:

• Read the content
• Note the file path
• Identify the general topic/purpose
• Check file size and complexity
  Create an inventory of files: ...

After:

Use the file-cataloger agent to discover and catalog all markdown files in specs/ and scratchpad/. Use the returned inventory table as the file list for all subsequent phases.

---

#### 2. `tone-analyzer` (`claude-haiku-4.5`)

**Extracted task**: Classify each markdown file for marketing-tone violations and formatting issues, returning a structured issues list.
**Why haiku**: Binary classification against a fixed word list ("great", "easy", "powerful") and mechanical formatting pattern-matching — textbook Haiku-adequate task.
**Score**: 9/10 (independence: 2, haiku-adequacy: 3, parallelism: 2, size: 2)
**Estimated savings**: ~7% of main-model tokens/run (~312,000 tokens)

<details>
<summary>Agent definition (copy-paste ready)</summary>

```markdown
## agent: `tone-analyzer`
---
description: Scan a markdown file for marketing language and formatting violations
model: claude-haiku-4.5
---
You receive a single file path. Read the file and perform two scans:

1. **Tone scan**: Find marketing/subjective language: "great", "easy", "powerful",
   "amazing", "simple", "seamless", "intuitive", or subjective adjectives without
   technical basis. For each: record line number, exact text, and a neutral replacement.

2. **Formatting scan**: Find code blocks without language tags, bold-style headings
   that should use `##` syntax, and lists longer than 5 items that could be prose.

Output JSON only:
{"file":"<path>","tone_issues":[{"line":N,"text":"...","suggestion":"..."}],
"formatting_issues":[{"line":N,"type":"...","context":"..."}]}

Invocation change in main prompt:

Before:

## Phase 2: Tone and Consistency Analysis

### 1. Check Technical Tone
For each markdown file, analyze:
**Tone Issues to Identify:**
- ❌ Marketing language ("great", "easy", "powerful", "amazing")
...
### 2. Check Formatting Consistency
Verify formatting standards: ...
### 3. Check for Mermaid Diagram Opportunities
...

After:

## Phase 2: Tone and Consistency Analysis

For each file in the inventory, use the `tone-analyzer` agent, passing the file path.
Collect all returned JSON objects into a combined issues list for Phase 3.
Also note any sections the agent flags as candidates for Mermaid diagrams.

---

Frontmatter Change Required

Add to frontmatter:

features:
  inline-agents: true

---

Estimated Impact

Metric	Before	After (estimated)
Avg tokens/run	~4,465,843	~3,773,000 (~15% reduction)
Main-model context saved	—	~693,000 tokens/run
Parallelism opportunity	None	Phase 2 files analyzed concurrently

Implementation Steps

1. Add features: inline-agents: true to frontmatter of .github/workflows/developer-docs-consolidator.md
2. Add the file-cataloger agent block at the bottom of the file, after all workflow content
3. Add the tone-analyzer agent block at the bottom of the file, after file-cataloger
4. Replace Phase 1 steps 1–3 with the single file-cataloger invocation line
5. Replace Phase 2 steps 1–3 with the single tone-analyzer loop invocation
6. Compile: gh aw compile developer-docs-consolidator
7. Test: gh workflow run developer-docs-consolidator.yml

References:

• Optimizer run: https://github.com/github/gh-aw/actions/runs/25283157400

Generated by Daily Sub-Agent Optimizer · ● 327.8K · ◷

• expires on May 10, 2026, 3:39 PM UTC