feat(coding-agent): walk one case step by step in explain-until-understood

[cheneeheng]

What

explain-until-understood gets a new procedure step — walk one real input through the mechanism,
one hop per numbered line — plus a first-day reader floor, a spelled-out ASCII charset for diagrams,
and a readability rewrite of the whole body. Released as repo tag v5.0.2 / ceh-coding-agent 3.1.2.

Why

Three observations from using the skill:

1. A worked example beat a general description every time, but the skill only reached for numbered
   steps as ladder attempt 2 — a recovery after an explanation had already missed.
2. "Assume the reader knows nothing about the subject" left project-local vocabulary uncovered: the
   repo, the work that led here, an internal acronym everyone says out loud.
3. "Draw in ASCII" never said which characters, so box-drawing and arrow glyphs passed. One glyph
   that fails to render breaks the picture exactly where the picture carries the meaning.

The skill also required "one new idea per sentence" while being written in eight-to-thirteen-line
paragraphs carrying four rules each.

How

The walk becomes step 5, placed after the drawing step so the picture is the map and the walk is
one journey across it; old steps 5-7 shift to 6-8 and all internal step references were re-checked.

The non-obvious decision is the collision with the escalation ladder, whose attempt 2 is numbered
steps: making a walk the default means attempt 2 is no longer a change of representation. Rejected
deleting that rung — it was the only step between prose and pictures. Disambiguated in prose
instead: a numbered walk inside prose is still attempt 1; attempt 2 is the whole explanation
rebuilt as steps.

The density pass restructures each procedure step as one bold claim plus sub-bullets. The Rules
section is a shared block with explain-codebase per docs/CROSS_REFERENCES.md and was left
byte-identical.

Testing

• python tools/validate-plugins/validate.py — green (this is the CI gate, validate.yml).
• Content preservation on the density pass verified with git diff --word-diff filtered to
  deletions: every removed phrase reappears in the sentence that replaced it.
• Line widths checked (no line over 100 chars in the new content); frontmatter re-parsed with
  yaml.safe_load to confirm the folded >- description still folds to one string.
• No behavioral test exists for whether the new step improves an explanation. ceh-evaluation would
  measure that and was not run.

Checklist

• All CI checks pass
• Tests added or updated for new behavior — n/a, prose-only repo
• No any / @ts-ignore / # type: ignore introduced
• No secrets or credentials in code
• Migrations (if any) are backward-compatible
• ARCHITECTURE.md Key Decisions updated — n/a; the ladder decision is logged in
  .agents_workspace/DECISION_LOG.md entry 84
• Attribution included if AI tooling assisted

Generated with Claude Code by CEH