Skip to content

Integrate readability planning coding - #136

Merged
mxriverlynn merged 10 commits into
han-v5.0.0-alpha-1from
integrate-readability-planning-coding
Jul 20, 2026
Merged

Integrate readability planning coding#136
mxriverlynn merged 10 commits into
han-v5.0.0-alpha-1from
integrate-readability-planning-coding

Conversation

@mxriverlynn

@mxriverlynn mxriverlynn commented Jul 20, 2026

Copy link
Copy Markdown
Collaborator

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-communication plugin). 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-build in han-planning; coding-standard, test-planning in han-coding) gain three things: a guidance-source line before drafting, one dispatch to the readability-editor agent 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-implementation writes 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.md and the readability-guidance skill. 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 declares han-communication as a direct dependency instead of reaching it transitively through han-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.

@mxriverlynn
mxriverlynn marked this pull request as ready for review July 20, 2026 17:49
@mxriverlynn
mxriverlynn merged commit d8697ac into han-v5.0.0-alpha-1 Jul 20, 2026
2 checks passed
@mxriverlynn
mxriverlynn deleted the integrate-readability-planning-coding branch July 20, 2026 17:49
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