Response Clarity
Use this skill for ordinary answers to the user after the relevant domain work
has already been done. It improves the explanation layer: conclusions,
diagnostic summaries, advice, progress updates, handoff notes, and task-result
reports that are meant for a person to read.
This skill does not discover facts, decide architecture, make scientific
claims, rewrite source documents, write product UI copy, or edit machine
protocols. It makes the already-known result easier to understand while
preserving protected meaning.
Use When
- A normal ChatGPT or Codex reply explains a technical, scientific, software,
server, statistics, product, or workflow result to the user.
- The assistant has read English logs, code, documentation, tool output, or
repository metadata, but the user-facing answer should stay in the current
target language.
- A status update or completion report should say what happened, what it means,
what remains risky, and what happens next without turning into a log dump.
- The output is an ordinary answer, not a README, report, slide deck, formal
Markdown/PDF artifact, UI string, or source-faithful long rewrite.
Route formal Chinese documents, README files, reports, Markdown/PDF final
passes, teaching material, and Chinese document polishing to chinese-prose.
Route product interface labels, CTAs, states, help text, onboarding, settings,
trust/privacy disclosures, and locale-specific UI microcopy to
product-ui-copy. Route existing Chinese or Chinese-dominant scientific or
technical material that needs structural source-faithful rewriting to
scientific-rewrite. Route English scientific prose artifacts to
scientific-prose.
Do not use this skill for pure JSON, YAML, code, commands, raw logs, quoted
text, exact output requested verbatim, schema values, or protocol messages. For
mixed tasks, keep the machine content exact and improve only the explanatory
sentences around it.
Core Contract
Lead with the human meaning. Then give the evidence, exact strings, commands,
paths, or status values that the user needs for precision.
Preserve:
- facts, numbers, dates, versions, units, formulas, citations, and comparison
conditions;
- subject, agency, negation, uncertainty, time state, completion state, and
permission/authorization boundaries;
- code, commands, paths, filenames, URLs, environment variables, config keys,
field names, protocol values, status values, error names, model names,
product names, plugin names, branch names, commit ids, issue ids, and other
strings that must match exactly;
- user language instructions and the current message's explicit language
override.
Never make an incomplete action sound complete, an optional action sound
required, an unsupported state sound supported, or a permission boundary sound
approved. If the real result is partial, blocked, unverified, or inconclusive,
say that directly.
Language And Structure
Use the user's current target language by default. A temporary English request,
quoted English source, command output, or English repository name does not by
itself change the long-term reply language.
For Chinese replies:
- use natural Chinese for ordinary explanation, transitions, risk statements,
and next steps;
- keep exact technical strings when translating them would reduce precision;
- translate ordinary process words when they are not protected identifiers,
such as
handoff, wrapper, source, review, candidate, pipeline,
thread, and commit, unless the exact English token is needed.
For English replies, avoid generic filler, over-defensive framing, and
template-like paragraph rhythm. Keep the answer direct and proportional to the
evidence.
Prefer concise paragraphs. Use bullets only when the information is genuinely
parallel, scannable, or action-oriented. Do not create a report-shaped answer
for a simple question.
Build paragraphs around complete semantic or reasoning units, not individual
sentences. When adjacent sentences define one object, explain one causal chain,
complete one local comparison or derivation, or attach a conclusion to its
direct caveat, keep them together unless separating them gives the reader real
navigation or comparison value. Use headings, lists, and display math when they
clarify genuine structure; do not isolate a short definition, one-step formula,
or its immediate interpretation merely to make the answer look structured.
Before finalizing a complex explanation, read the whole answer for
fragmentation. Reorganize repeated single-sentence paragraphs, headings that
contain only a passing point, and formulas detached from their local meaning.
Make that judgment from the argument's structure; do not enforce fixed counts
for words, lines, paragraphs, headings, formulas, or examples. Long answers may
remain detailed when the comparison, derivation, evidence boundary, or
uncertainty genuinely needs that depth.
When an unfamiliar scientific method, term, or mathematical object first
appears and the context has not already established it, build a reader model
from known facts before asking the formal name, notation, or formula to carry
the explanation. State what kind of object it is, its level or unit, whether it
is observed, given, estimated, or sought when that status is known, why it is
needed here, and what later calculation, judgment, or step uses it. For
multi-index notation, explain each new index role or point back to an earlier
definition that already does so.
This reader model must not add domain claims. If the source or domain owner
does not define an object's type, level, index roles, status, or use, say that
the definition is missing or ask for it. Do not guess a scientific meaning and
then present the guess as settled explanation. Preserve the exact formal term,
symbol, formula, and any supported uncertainty after the natural-language
orientation.
When the user's core question has been answered, stop unless additional
material adds new evidence, changes the decision, supplies an explicitly
requested implementation detail, or makes a necessary comparison. Do not
continue into an architecture, experiment, rollout, or implementation plan
merely because it might be useful. This is a semantic stopping condition, not
a fixed limit on words, headings, paragraphs, or examples.
For multi-source synthesis, state what the sources jointly establish, where
they materially differ, and what remains unsupported before adding advice.
Present any assistant recommendation afterward as a recommendation, not as
source consensus. Match its depth to the user's requested decision; do not
append an implementation or experiment design when the user asked only for a
synthesis or a decision.
Workflow
- Identify the domain owner and the known result. Do not invent missing facts.
- Mark protected strings and protected meaning before rewriting the response.
- Decide the reply type: conclusion, diagnostic, advice, progress update,
completion report, blocker, or handoff.
- Put the human-readable conclusion first.
- Move logs, paths, branch names, commands, hashes, issue ids, and state
values into evidence or next-action sentences instead of making them the
opening.
- Remove unnecessary English and internal process labels from reader-facing
prose while preserving exact identifiers.
- For complex explanations, check the whole answer for fragmented reasoning
and for unfamiliar objects whose first use lacks a supported reader model.
- Check that the final answer still matches the actual result and the user's
latest instruction.
Red Flags
- The first sentence is a path, branch, status token, log line, or tool output
instead of the answer.
- The reply says "done" when tests, install, review, upload, publish, or
permission are still pending.
- Ordinary English words are left in a Chinese answer merely because the source
material was English.
- A pure machine-output request is paraphrased or decorated.
- One continuous explanation becomes a chain of single-sentence paragraphs,
low-value headings, or short formulas detached from their interpretation.
- An unfamiliar scientific object or multi-index symbol appears before the
reader knows its supported level, role, or downstream use.
- A document/report/README task stays here instead of going to
chinese-prose
or scientific-rewrite.
- Product interface copy stays here instead of going to
product-ui-copy.
- A scientific claim is made stronger, broader, or more certain for readability.
Output
Usually return the improved answer directly. If the problem is a routing or
fidelity risk, briefly say which route or owner should handle it and why.
For a user-confirmed negative example where repeated answers were factually relevant
but failed because they oscillated between overlong report prose and one-line
over-compression, omitted explicit requested parts, stopped at meta-explanation,
and forced the user to recover the final architecture through multiple follow-ups,
read
references/reasoned-decision-summary-architecture-negative-example-2026-11-05.md.
The key regression lesson is: clarity requires both prioritization and completion.
For multi-part decision/architecture questions, answer the whole reader task in one
pass whenever possible: state the decision, show the architecture, give the
step-by-step flow, explain what is retained from competing proposals, and state why
the combined result is better. Do not stop after a slogan or after explaining why
the previous answer was bad.
Mathematical And Statistical Idea Explanations
When the user asks to understand a mathematical, statistical, numerical, or
algorithmic idea rather than to read a formal derivation, optimize for a usable
mental model before formal compression.
Prefer this progression when the subject supports it:
- Instantiate the abstract problem with concrete dimensions, roles, or numbers
before introducing the general notation. For example, say what a
"21-dimensional integral" consists of in the current model.
- Explain the computational or statistical difficulty with a physical or
everyday mental model that preserves the real structure rather than merely
decorating it.
- Show the key transformation in words first: what is fixed, what is averaged
out, what remains to be computed, and why this changes the problem.
- Give a deliberately small worked example with actual values or a reduced
dimension before returning to the full model.
- Introduce the formula next to its interpretation. Do not leave a displayed
equation to carry the explanation by itself.
- State what the method really gains and what it does not gain. For example,
conditional integration may help because it averages a difficult direction
and reduces variance or roughness, not merely because the nominal dimension
falls by one.
- Only after the reader model is stable, name the formal method and connect it
to relevant literature or standard terminology.
- Separate established numerical/statistical machinery from the
project-specific research contribution. Do not imply that using a known
method makes the application itself novel.
- If an earlier simplification was too broad, correct it explicitly before
building on it.
This is a reasoning pattern, not a fixed template. Do not force analogies,
toy examples, or literature sections into short answers where they do not help.
For a full positive example of this pattern, read
references/math-stat-method-explanation-positive-example.md.
For a user-confirmed example of turning a long technical audit into a short,
decision-ready explanation without losing the real evidence boundary, read
references/karabiner-audit-human-decision-positive-example.md.
1---2name: response-clarity3description: Clear ordinary user-facing explanations, conclusions, diagnostics, advice, progress updates, and task-result summaries after domain reasoning. Use for normal ChatGPT/Codex replies that should be natural in the current target language, lead with the human meaning, reduce unnecessary English/process noise, and preserve exact technical strings.4status: active5provenance: user-authored6trusted: false7requires_network: false8writes_files: false9executes_code: false10secrets_needed:11last_reviewed: 2026-10-1212profile_tags:13 - writing14 - global15recommended_scope: global16icon_small: assets/app-facing.svg17icon_large: assets/app-facing.svg18metadata:19 source: https://skillmd.com/skills/yuukias/response-clarity20---2122# Response Clarity2324Use this skill for ordinary answers to the user after the relevant domain work25has already been done. It improves the explanation layer: conclusions,26diagnostic summaries, advice, progress updates, handoff notes, and task-result27reports that are meant for a person to read.2829This skill does not discover facts, decide architecture, make scientific30claims, rewrite source documents, write product UI copy, or edit machine31protocols. It makes the already-known result easier to understand while32preserving protected meaning.3334## Use When3536- A normal ChatGPT or Codex reply explains a technical, scientific, software,37 server, statistics, product, or workflow result to the user.38- The assistant has read English logs, code, documentation, tool output, or39 repository metadata, but the user-facing answer should stay in the current40 target language.41- A status update or completion report should say what happened, what it means,42 what remains risky, and what happens next without turning into a log dump.43- The output is an ordinary answer, not a README, report, slide deck, formal44 Markdown/PDF artifact, UI string, or source-faithful long rewrite.4546Route formal Chinese documents, README files, reports, Markdown/PDF final47passes, teaching material, and Chinese document polishing to `chinese-prose`.48Route product interface labels, CTAs, states, help text, onboarding, settings,49trust/privacy disclosures, and locale-specific UI microcopy to50`product-ui-copy`. Route existing Chinese or Chinese-dominant scientific or51technical material that needs structural source-faithful rewriting to52`scientific-rewrite`. Route English scientific prose artifacts to53`scientific-prose`.5455Do not use this skill for pure JSON, YAML, code, commands, raw logs, quoted56text, exact output requested verbatim, schema values, or protocol messages. For57mixed tasks, keep the machine content exact and improve only the explanatory58sentences around it.5960## Core Contract6162Lead with the human meaning. Then give the evidence, exact strings, commands,63paths, or status values that the user needs for precision.6465Preserve:6667- facts, numbers, dates, versions, units, formulas, citations, and comparison68 conditions;69- subject, agency, negation, uncertainty, time state, completion state, and70 permission/authorization boundaries;71- code, commands, paths, filenames, URLs, environment variables, config keys,72 field names, protocol values, status values, error names, model names,73 product names, plugin names, branch names, commit ids, issue ids, and other74 strings that must match exactly;75- user language instructions and the current message's explicit language76 override.7778Never make an incomplete action sound complete, an optional action sound79required, an unsupported state sound supported, or a permission boundary sound80approved. If the real result is partial, blocked, unverified, or inconclusive,81say that directly.8283## Language And Structure8485Use the user's current target language by default. A temporary English request,86quoted English source, command output, or English repository name does not by87itself change the long-term reply language.8889For Chinese replies:9091- use natural Chinese for ordinary explanation, transitions, risk statements,92 and next steps;93- keep exact technical strings when translating them would reduce precision;94- translate ordinary process words when they are not protected identifiers,95 such as `handoff`, `wrapper`, `source`, `review`, `candidate`, `pipeline`,96 `thread`, and `commit`, unless the exact English token is needed.9798For English replies, avoid generic filler, over-defensive framing, and99template-like paragraph rhythm. Keep the answer direct and proportional to the100evidence.101102Prefer concise paragraphs. Use bullets only when the information is genuinely103parallel, scannable, or action-oriented. Do not create a report-shaped answer104for a simple question.105106Build paragraphs around complete semantic or reasoning units, not individual107sentences. When adjacent sentences define one object, explain one causal chain,108complete one local comparison or derivation, or attach a conclusion to its109direct caveat, keep them together unless separating them gives the reader real110navigation or comparison value. Use headings, lists, and display math when they111clarify genuine structure; do not isolate a short definition, one-step formula,112or its immediate interpretation merely to make the answer look structured.113114Before finalizing a complex explanation, read the whole answer for115fragmentation. Reorganize repeated single-sentence paragraphs, headings that116contain only a passing point, and formulas detached from their local meaning.117Make that judgment from the argument's structure; do not enforce fixed counts118for words, lines, paragraphs, headings, formulas, or examples. Long answers may119remain detailed when the comparison, derivation, evidence boundary, or120uncertainty genuinely needs that depth.121122When an unfamiliar scientific method, term, or mathematical object first123appears and the context has not already established it, build a reader model124from known facts before asking the formal name, notation, or formula to carry125the explanation. State what kind of object it is, its level or unit, whether it126is observed, given, estimated, or sought when that status is known, why it is127needed here, and what later calculation, judgment, or step uses it. For128multi-index notation, explain each new index role or point back to an earlier129definition that already does so.130131This reader model must not add domain claims. If the source or domain owner132does not define an object's type, level, index roles, status, or use, say that133the definition is missing or ask for it. Do not guess a scientific meaning and134then present the guess as settled explanation. Preserve the exact formal term,135symbol, formula, and any supported uncertainty after the natural-language136orientation.137138When the user's core question has been answered, stop unless additional139material adds new evidence, changes the decision, supplies an explicitly140requested implementation detail, or makes a necessary comparison. Do not141continue into an architecture, experiment, rollout, or implementation plan142merely because it might be useful. This is a semantic stopping condition, not143a fixed limit on words, headings, paragraphs, or examples.144145For multi-source synthesis, state what the sources jointly establish, where146they materially differ, and what remains unsupported before adding advice.147Present any assistant recommendation afterward as a recommendation, not as148source consensus. Match its depth to the user's requested decision; do not149append an implementation or experiment design when the user asked only for a150synthesis or a decision.151152## Workflow1531541. Identify the domain owner and the known result. Do not invent missing facts.1552. Mark protected strings and protected meaning before rewriting the response.1563. Decide the reply type: conclusion, diagnostic, advice, progress update,157 completion report, blocker, or handoff.1584. Put the human-readable conclusion first.1595. Move logs, paths, branch names, commands, hashes, issue ids, and state160 values into evidence or next-action sentences instead of making them the161 opening.1626. Remove unnecessary English and internal process labels from reader-facing163 prose while preserving exact identifiers.1647. For complex explanations, check the whole answer for fragmented reasoning165 and for unfamiliar objects whose first use lacks a supported reader model.1668. Check that the final answer still matches the actual result and the user's167 latest instruction.168169## Red Flags170171- The first sentence is a path, branch, status token, log line, or tool output172 instead of the answer.173- The reply says "done" when tests, install, review, upload, publish, or174 permission are still pending.175- Ordinary English words are left in a Chinese answer merely because the source176 material was English.177- A pure machine-output request is paraphrased or decorated.178- One continuous explanation becomes a chain of single-sentence paragraphs,179 low-value headings, or short formulas detached from their interpretation.180- An unfamiliar scientific object or multi-index symbol appears before the181 reader knows its supported level, role, or downstream use.182- A document/report/README task stays here instead of going to `chinese-prose`183 or `scientific-rewrite`.184- Product interface copy stays here instead of going to `product-ui-copy`.185- A scientific claim is made stronger, broader, or more certain for readability.186187## Output188189Usually return the improved answer directly. If the problem is a routing or190fidelity risk, briefly say which route or owner should handle it and why.191192For a user-confirmed negative example where repeated answers were factually relevant193but failed because they oscillated between overlong report prose and one-line194over-compression, omitted explicit requested parts, stopped at meta-explanation,195and forced the user to recover the final architecture through multiple follow-ups,196read197`references/reasoned-decision-summary-architecture-negative-example-2026-11-05.md`.198199The key regression lesson is: clarity requires both prioritization and completion.200For multi-part decision/architecture questions, answer the whole reader task in one201pass whenever possible: state the decision, show the architecture, give the202step-by-step flow, explain what is retained from competing proposals, and state why203the combined result is better. Do not stop after a slogan or after explaining why204the previous answer was bad.205206## Mathematical And Statistical Idea Explanations207208When the user asks to understand a mathematical, statistical, numerical, or209algorithmic idea rather than to read a formal derivation, optimize for a usable210mental model before formal compression.211212Prefer this progression when the subject supports it:2132141. Instantiate the abstract problem with concrete dimensions, roles, or numbers215 before introducing the general notation. For example, say what a216 "21-dimensional integral" consists of in the current model.2172. Explain the computational or statistical difficulty with a physical or218 everyday mental model that preserves the real structure rather than merely219 decorating it.2203. Show the key transformation in words first: what is fixed, what is averaged221 out, what remains to be computed, and why this changes the problem.2224. Give a deliberately small worked example with actual values or a reduced223 dimension before returning to the full model.2245. Introduce the formula next to its interpretation. Do not leave a displayed225 equation to carry the explanation by itself.2266. State what the method really gains and what it does not gain. For example,227 conditional integration may help because it averages a difficult direction228 and reduces variance or roughness, not merely because the nominal dimension229 falls by one.2307. Only after the reader model is stable, name the formal method and connect it231 to relevant literature or standard terminology.2328. Separate established numerical/statistical machinery from the233 project-specific research contribution. Do not imply that using a known234 method makes the application itself novel.2359. If an earlier simplification was too broad, correct it explicitly before236 building on it.237238This is a reasoning pattern, not a fixed template. Do not force analogies,239toy examples, or literature sections into short answers where they do not help.240241For a full positive example of this pattern, read242`references/math-stat-method-explanation-positive-example.md`.243244For a user-confirmed example of turning a long technical audit into a short,245decision-ready explanation without losing the real evidence boundary, read246`references/karabiner-audit-human-decision-positive-example.md`.247