The Deep Document Optimizer — A Live Run

This is a lightly trimmed transcript of a Claude Code session from 17 June 2026. /ddo is the Document Deep Optimizer, a skill that audits a document in numbered passes (0 to 14, with sub-passes such as 3.5, 10.5 and 11.5), applies every medium-or-higher fix in place, and repeats until none remain or an iteration cap is reached. I pointed it at a messy file: an export of a Slack thread about my skills tooling, with two pasted Claude conversations appended. Markdown escapes had corrupted nearly every line, and Slack residue was scattered through it.

Four things are worth watching. The optimizer writes a contract and a routing decision before it touches anything. It exempts quoted material from rewriting. After the edit it runs a verification gate, and when one check raises a false alarm it works out why. And it flags its one judgment-call deletion, with a rollback command.

The two pasted conversations in the target file appear in full in Orientation — Worked Examples. The skill, prompt, document and code optimizers (sko, pdo, ddo and cdo) are compared in Semantic Skill Discovery and the Optimizer Family. In the transcript, Claude’s narration and reports are plain text, tables and a blockquote. Code blocks hold tool calls, their output and the final confirmation lines. My own interjections are in italics. Notes on what I trimmed and removed are at the end.

Prompt and setup

❯ Use the deep document optimizer on this filee ~/Downloads/skills_showcase.md

I’ll use the Document Deep Optimizer on that file. Let me start by reading it, then invoke the skill.

⏺ Read(~/Downloads/skills_showcase.md)
  Read 260 lines

This is a Slack-thread export (your infodump about the skill ecosystem) with two pasted Claude transcripts appended. I’ll run the Document Deep Optimizer on it. Let me invoke the skill.

⏺ Skill(ddo)
  Successfully loaded skill

⏺ Read(~/.claude/skills/writing-expert/references/ddo/SKILL.md)
  Read 520 lines
  Loaded .claude/CLAUDE.md

The skill and its instructions are loaded. This is a multi-step run, so let me set up task tracking and load the engine’s supporting references in parallel.

⏺ Read(~/.claude/skills/writing-expert/references/document-critique.md)
  Read 327 lines

⏺ Read(~/.claude/skill-consolidation/convergence-and-severity.md)
  Read 258 lines

⏺ Read(~/.claude/skills/writing-expert/references/kill-the-AI-ism.md)
  Read 278 lines

⏺ Read(~/.claude/skills/writing-expert/references/ddo/references/severity-calibration.md)
  Read 45 lines

The first read of the severity table, at ddo/severity-calibration.md, shows no result in my copy. Two directory listings follow, and the table turns up under ddo/references/, next to writing-skills.md.

I have the engine, the canonical convergence/severity model, the voice layer, and the severity-calibration table. Let me set up task tracking and take the mandatory pre-write snapshot.

⏺ Bash(TS=$(date +%Y%m%d-%H%M%S); DIR=~/.claude/skill-consolidation/backups/ddo-$TS; mkdir -p "$DIR"; cp ~/Downloads/skills_showcase.md "$DIR/skills_showcase.md" && echo "Snapshot: $DIR/skills_showcase.md" && wc -w ~/Downloads/skills_showcase.md)
  Snapshot: ~/.claude/skill-consolidation/backups/ddo-20260617-123209/skills_showcase.md
  2737 ~/Downloads/skills_showcase.md

Snapshot saved (2,737 words). Here’s the optimization contract and routing.

The contract and routing

Optimization contract (Step 2):

Writing-skill routing (Step 2.5):

Insight

• The decisive call here is the quoted-material immunity: the two appended Claude transcripts are exhibits, not prose to re-optimize. Pass 13’s immunity list protects directly-quoted material, so I de-corrupt their markdown but never rewrite their sentences. That neatly avoids “re-optimizing already-optimized text.”
• The author’s candid asides are voice + content on an internal doc, not meta-artifacts — DDO’s “opinion I disagree with → never a finding” rule means I keep them. I’m cleaning the paste, not sanitizing the person.

The audit

Now running the critique passes.

Pass 0 — Domain awareness: skill/prompt engineering + MongoDB TAM tooling. Activated writing-expert, kill-the-AI-ism. No regulated domain. Pass.

Findings table (calibrated for a general-prose showcase):

Pass 6 (completeness), Pass 3 (technical): showcase, not operational — no rollback/blockers needed; self-reported claims internally consistent. Pass.

The rewrite

Findings recorded. Applying fixes now.

Nearly every line carries escape corruption, so I’ll rewrite the file in one pass (de-escape + restructure + reproduce the transcripts faithfully as exhibits).

⏺ Write(~/Downloads/skills_showcase.md)
  Added 100 lines, removed 163 lines

The diff view runs to about 360 lines in my copy, interleaving old and new text. Most of it is the two appended Claude transcripts, which the optimizer says it kept verbatim as exhibits. Here is the new heading skeleton:

# Skills Ecosystem — Showcase
## The pieces I've built
## Meta-research: saturating a concept family
## Hub-and-spoke architecture (taming skill sprawl)
## Why I lean on skills over agents
## Semantic skill matching (proof of concept)
## Real-world tests
### Credit & personal finance
### Incident-responder training for a customer
## Where it started: mdb-tam and the case-triage extension
## Appendix: example sessions
### Example 1 — Explaining the optimizer family
#### 1. repo-bootstrapper — "repo-kickstarter"
#### 2. ddo / document-critique — "deep document"
#### 3. sko / skill-optimizer — "skill"
#### 4. cdo / code-deep-optimizer — "code"
#### 5. pdo / prompt-deep-optimizer — "prompt"
#### 6. deso / design-deep-optimizer — "image"
### Example 2 — /dr and the concept-family explorer

The verification gate

Running the post-edit verification gate (Step 5.5) — mechanical integrity, fact-preservation, delta bound.

⏺ Bash(post-edit gate: word count, code-fence parity, heading levels, residual escape artifacts, URL list, Slack-cruft residue)
  === word count ===
  2406 ~/Downloads/skills_showcase.md
  === code fences (should be even) ===
  4
  === heading levels ===
  (19 headings: 1 H1, 8 H2, 4 H3, 6 H4)
  === residual escape artifacts (should be 0) ===
  0
  === all URLs preserved ===
  (six links to internal repos and Slack files, omitted here)
  === Slack-cruft residue (should be 0) ===
  0

Gate passes: fences balanced (2 blocks), headings monotonic (#→##→###→####, no skips), 0 escape artifacts, 0 Slack cruft, all 6 showcase URLs intact. Word delta 2737 → 2406 (−12.1%) — a reduction from cleanup (no growth justification needed). Quick terminology/typo confirmation:

⏺ Bash(count residual typos, lowercase term leaks, and any surviving text from the opening context-doc/Aha question)
  === residual typos (should be 0) ===
  8
  === lowercase term leaks in prose (glean/mcp as standalone words) ===
  none
  === opening context-doc/Aha text fully removed (should be 0) ===
  0

The count is inflated by case-insensitive matching (WHIch matches every “which”/“Which”). Let me check the actual misspellings case-sensitively.

⏺ Bash(case-sensitive grep for the exact misspellings, then confirm the "overhead" fix landed)
  === exact misspellings (case-sensitive, should be 0) ===
  none — all fixed
  === 'skill overhead' present (the line-28 fix) ===
  21:One of the big issues is having too MANY skills that eat up your context. So I folded the skills into a hub-and-spoke architecture where they all cross-reference each other with specific "when to use" and "when not to use" sections — so they automatically route queries to the right skills without yet another agent or skill adding overhead.

All Medium+ findings applied; typos fixed, terminology standardized, opener removed. Pre-exit intent check: audience (internal), reader-action (navigable showcase), and constraints (transcripts verbatim, URLs preserved) all hold — no intent drift. A fresh re-read surfaces no corroborated Medium+ findings. Converged — clean (1 iteration, small profile).

Appending telemetry (fail-safe) and closing out.

⏺ Bash(append four per-pass rows to ~/.claude/skill-consolidation/optimizer-telemetry.jsonl)
  telemetry appended (4 rows)

The close-out report

/ddo complete — converged clean in one iteration.

6a. Iteration summary

6b. Pass scorecard (final)

6c. Top-5 most impactful edits

1. De-escaped the entire document — [ ] # ~ < > _ . rendered as literal backslashes on every line; now clean markdown.
2. Added a 9-section structure + exhibit appendix — the flat Slack dump is now a navigable showcase; the two transcripts are framed as “Example sessions.”
3. Removed the off-topic context-doc/Aha opener (orig. lines 1–5) — unanswered account-admin fragments that contradicted the showcase purpose. Flagged: this is the one judgment-call deletion — see below.
4. Stripped Slack-UI cruft — standalone timestamps, duplicate speaker labels, the triplicated zip link, “1x”, and the “| Screen Recording…mov” fragment.
5. Standardized terminology + fixed 8 typos (experience, overhead, functionality, Which, training, expertise, “an agent”, kind of).

6d. Deferred (Minor/Nit) and preserved-by-design

• Kept your voice and candid asides — they are content/voice on an internal doc, not artifacts. DDO doesn’t sanitize the author.
• Transcripts not rephrased — they’re directly-quoted exhibits (Pass 13 immunity); I only restored their corrupted markdown.

6e. File confirmation

Optimized document written to: ~/Downloads/skills_showcase.md
Original: 2737 words → Optimized: 2406 words (−12.1%)
Exit: CONVERGED_CLEAN (1 iteration, small profile)

One thing to confirm: I removed the opening context-doc + Aha-report question (and their two links — a Google Doc and an Aha share link) as accidental paste residue unrelated to the showcase. If that was intentional, restore from the snapshot.

Snapshot & rollback:

cp ~/.claude/skill-consolidation/backups/ddo-20260617-123209/skills_showcase.md ~/Downloads/skills_showcase.md

Notes on this transcript

• I cut repeated reads, the directory listings, the task-tracking calls, the diff body, a closing recap that repeated the report, and three short narration lines that only announced the next read. I turned the contract and routing lists into tables, reformatted the other tables as Markdown, dropped an all-dash “Calibrated?” column and the check marks, showed the “Insight” box as a blockquote, bolded the 6a to 6e labels, and changed the warning sign on the judgment-call deletion to the word “Flagged”. The parenthesised lines inside the gate output are my condensed summaries of the original listings. Claude’s narration and reports are otherwise as they appeared.
• The target file named an account in its opening fragment and a customer in its incident-responder training example. Every mention of those names is replaced by neutral wording or removed, as is an Aha share-link domain and every internal repo, Slack and Google Doc link. Home-directory paths appear as ~.
• The regular expressions in the verification commands lost their backslashes when I copied the session. I describe each command and keep its output instead of reproducing a pattern that would not run as shown.
• The close-out report says “9 navigable sections”. The gate’s heading listing, condensed above, shows one title heading and eight second-level headings, one of them the appendix. I left Claude’s figure as it appeared.
• One narration line in my copy ended mid-word (“small pr”). I completed it as “small profile”, which is what the closing exit line says.
• The session date, 17 June 2026, comes from the snapshot folder name.