feat(han-communication): add the han-concise output style and tighten technical-detail separation - #189
Merged
Merged
Conversation
Han Concise carries everything Han Readability does — the audience frame, the output properties, the writing voice, the vocabulary blocklist, the prose-only scope, the fidelity guard, the break-a-rule escape, and the seven-criterion self-check — plus a brevity property the canonical rule does not carry. A turn drops preamble and recap, spends no sentence that carries neither a fact nor a needed transition, and reserves headings for responses with parts worth navigating. Brevity comes out of filler only; the fidelity guard still holds every fact. The brevity property stays out of readability-rule.md on purpose, so it shapes the conversation and leaves every Han skill's deliverable alone. Han Readability is unchanged. The new style ships with its long-form doc, a plugin README scent line, and updates to the readability guide, the plugin index, the coverage rule, the contributor guide, and the project map.
Fidelity wins is the wrong default for a style whose whole point is brevity. Claiming every fact survives at full precision forces the reader to ask for less before they get it, and asks the output to be anything but concise. Han Concise now assumes the reader wants less than the source carries. Supporting detail rolls up into the statement it supports whenever the detail adds no meaningful value or clarification. A roll-up has to be true of everything it covers, so it is never a blur: the shorter true statement wins, the vaguer one never does. Three things stay at full precision. A fact whose loss would change what the reader does next, a number they will act on, and a stated condition that bounds when a claim holds. Self-check criterion 6 is rewritten from "Every fact preserved" to check the roll-up against that floor. Han Readability is unchanged and still preserves every fact, so the two styles now differ on fidelity as well as brevity. Both departures stay out of readability-rule.md, so Han's skills keep the canonical rule.
…y default The old wording read as permissive. "Keep it out of the readable paragraphs, where one must sit inline keep it small" left inline as an open option, and a first real session produced numbered steps threading file paths, method signatures, and shell commands through every sentence. Each detail was correct and the result was unreadable. Separation is now the default and inline is the exception: one identifier the sentence is genuinely about, kept only where pulling it out would leave the sentence pointing at nothing. A paragraph or list item threading several paths, signatures, or snippets through its sentences has failed the property, however accurate each one is. The drafting property alone was what got ignored, so the self-check now enforces it. Criterion 6 is new, the roll-up criterion moves to 7, and the shape criterion moves to 8 and keeps its precedence.
…il too The soft wording that let han-concise thread paths, signatures, and shell commands through its sentences is the same wording han-readability carries, and the failure mode is identical. Both styles now make separation the default and reserve inline for the one identifier a sentence is genuinely about. han-readability's self-check gains the same criterion at position 6, so it runs eight criteria: the rule's seven plus Technical detail separated. The fact criterion moves to 7 and the shape criterion to 8, keeping its precedence. That makes the technical-detail property a departure both styles share from readability-rule.md, which still leaves inline detail an open option. The docs record it as deliberate on both sides so a sync pass does not read it as drift, and Han's skills keep the canonical rule until we decide to move it there.
mxriverlynn
changed the title
… rule Both output styles had already tightened this property against readability-rule.md, which still left inline detail an open option. Two styles disagreeing with the rule on the same point is the signal the rule is the one that is wrong, so the tightened version moves into the canonical file and the styles stop departing from it. The rule's property now makes separation the default and reserves inline for the one reference a sentence is genuinely about. Its standardized self-check gains Technical detail separated at position 6, so it runs eight criteria: the fact criterion moves to 7 and the shape criterion to 8, keeping its precedence. The readability-editor rubric follows. Its progressive-disclosure criterion was carrying the technical-detail move as a trailing clause; that move is now its own criterion 7, and the shape criterion is 8. Every Han skill that sources the rule now drafts and checks against the tightened property. The docs that recorded the departure as deliberate are back to describing the styles as plain derived copies, and han-concise is down to its two remaining departures.
mxriverlynn
changed the title
…rion count The rubric moved to eight criteria when technical-detail separation was promoted, but the anti-pattern list still told the agent to apply seven.
The suite ships two output styles now, and the contributor guide had a checklist for adding a skill and one for adding an agent but nothing for adding a style. The new section names the file locations, the long-form doc requirement the coverage rule already carries, the README scent line, and the rule that a departure from a canonical reference gets recorded as deliberate.
… full Both operator-facing docs paraphrased it as "sentence length", dropping the active-voice half the agent's own rubric asks for.
mxriverlynn
marked this pull request as ready for review
August 20, 2026 14:35
Merged
mxriverlynn
added a commit
that referenced
this pull request
Aug 20, 2026
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
1 participant
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 adds a shorter-register output style and makes technical-detail separation a checked criterion of the canonical readability standard, so you can select a terser session and every prose-producing skill now keeps file paths and signatures out of its sentences.
Behavior changes
The new
han-conciseoutput style gives you a shorter register to select. An output style is a block of text Claude Code appends to the system prompt once at session start, chosen in/config, so it shapes every turn of that session.han-concisecarries the same Human-Readable Output Standard as the existinghan-readabilitystyle, with two deliberate differences. It drops preamble and recap, and it rolls detail up by default instead of carrying every fact through. Nine near-identical passing checks become "all nine passed". A floor holds it back from vagueness. It keeps at full precision any fact whose loss would change what you do next, any number you will act on, and any stated condition that bounds a claim.The second mechanism reaches further.
readability-rule.mdis the standard every prose-producing Han skill loads at runtime, so a change there changes what all of them write. "Technical detail follows the prose" was already one of its output properties, but nothing checked it and the wording left inline detail an open option. It now makes separation the default, and it has its own self-check criterion with a testable failure. A paragraph or list item that threads several paths, signatures, or snippets through its sentences has failed, however accurate each one is.The
readability-editoragent and thehan-readabilitystyle carry the same criterion. Both rubrics grow from seven criteria to eight, which renumbers the reader's-stated-shape criterion, the one that wins real collisions, from 7 to 8. In the editor's rubric the technical-detail move had been a trailing clause on progressive disclosure; it is now its own criterion. The remaining files are operator-facing documentation for the new style and the renumbering, plus a CONTRIBUTING checklist for adding an output style.