Integrate readability planning coding - #136
Merged
mxriverlynn merged 10 commits intoJul 20, 2026
Merged
Conversation
…ency, split rationale, scope reconciliation)
… anchors and cross-refs
…fication in readability-guidance
…D4/D9, fix guidance-echo wording
…munication directly
…five full-pattern skills
…o two lightweight skills
mxriverlynn
marked this pull request as ready for review
July 20, 2026 17:49
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR wires Han's shared readability standard into seven planning and coding skills that previously skipped it. The specs, plans, standards, and test plans a human reads end to end now meet the same quality bar as every other prose deliverable in the suite.
Behavior changes
The central mechanism is a shared "readability standard" (Han's Human-Readable Output Standard: a readability rule plus a writing-voice profile, both owned by the foundational
han-communicationplugin). Seven skills that produce human-read artifacts now source that standard while drafting and hold their output to it before presenting. This closes a gap where these artifact types slipped through unchecked.The seven skills split into two patterns. Five "full pattern" skills (
plan-a-feature,plan-implementation,plan-a-phased-buildinhan-planning;coding-standard,test-planninginhan-coding) gain three things: a guidance-source line before drafting, one dispatch to thereadability-editoragent after their final content exists, and a six-point self-check before presenting. Two "lightweight pattern" skills (plan-work-items,iterative-plan-review) gain the guidance-source line and the self-check only, with no editor dispatch.To keep the editor from touching structure, each skill names its own downstream reader (for example,
plan-implementationwrites for "the engineer who will build the feature") and its own citation-ID scheme to leave alone (D-N,W-N,TP-NNN, phase and open-question anchors). That way, identifiers and structured fields are never rewritten.Two supporting changes make this work. The standard's own scope text was reconciled in
readability-rule.mdand thereadability-guidanceskill. Now a spec, plan, phased build, work-item list, coding standard, or test plan counts as reader-facing whenever a human reads it end to end. Only a pure pipeline artifact consumed solely by downstream skills is excluded. Previously that text read as excluding the exact artifacts these skills produce.Separately,
han-planning's manifest now declareshan-communicationas a direct dependency instead of reaching it transitively throughhan-core.Long-form doc updates, a version bump, and CHANGELOG edits are intentionally out of scope and handled later.
The relevant files are the ten skill, manifest, and reference files listed above. The rest of the diff is planning artifacts under
docs/plans/readability-in-planning-coding/(spec, decision logs, review findings, implementation plan). These record how the change was designed and are not part of the shipped behavior.