Consolidate human-facing writing in explain-clearly by citypaul · Pull Request #278 · citypaul/.dotfiles · GitHub
Skip to content

Consolidate human-facing writing in explain-clearly - #278

Draft
citypaul wants to merge 2 commits into
mainfrom
codex/explain-clearly
Draft

citypaul wants to merge 2 commits into
mainfrom
codex/explain-clearly

Conversation

@citypaul

@citypaul citypaul commented Oct 8, 2026 •

Copy link
Copy Markdown
Owner

Replace the overlapping human-writing workflows with one automatically selected explain-clearly skill for plain English, documentation, messages, and HTML explainers. It combines meaning-preserving editing, explanation structure, typography, accessibility, and verification, with supporting references by output type.

The installer selects the new skill and archives technical-writing, simple-english, and clarity outside discovery after a successful upgrade. Local customisations remain recoverable. Repository guidance and agents now point to the consolidated skill. The changeset marks the retired skill name as a breaking change.

The existing promptfoo harness now has a three-arm artifact suite, deterministic grader proofs, lifecycle isolation controls, and repeated model-rubric calibration. The suite preserves generated content and prevents deferred cleanup or timed-out cases from contaminating later arms.

Evidence

  • Automatic selection: 12/12 writing checks across three repeats; 6/6 unrelated-request controls pass.
  • 18 offline grader checks, 3 lifecycle controls, and 10 repeated model calibration cases pass.
  • Revised prose: forced skill 14/15 metrics across three repeats; automatic selection 13/15. Unsupported reassurance remains a real miss. One automatic-arm failure was a rubric false positive on purpose versus outcome; the rubric was corrected and calibrated, without retrospectively changing that recorded score.
  • HTML snapshots were inspected in Chromium at 1280px and 320px. Keyboard input, presets, and 59/60/89/90-second transitions work. A later snapshot fixes the initially misplaced 60/90 labels and the conditional promise. Its endpoint label still overflows by 9px at 320px; guidance now covers inward anchoring, with confirmation pending.
  • Frontmatter, eval wiring, installer migration, and focused repository checks pass. git diff --check passes.
  • The full repository test runner stops at a pre-existing architecture-guidance assertion about the unchanged twelve-factor skill. The missing phrase and source are unchanged from the base revision.

Why this remains a draft

Prose faithfulness is not yet reliable across repeats. HTML agent runs timed out after 15 and 7 minutes, so the full automated three-arm HTML comparison is incomplete; browser findings from saved snapshots are separate evidence, not a passing eval claim. evals/skills/COVERAGE.md records the exact limits and the skill is not marked max.

No global skills were installed or removed during this work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant