Clarify a dense artifact into something you can act on

You were just handed a wall of text, an interview round with seven
cross-referenced questions, a design memo thick with session jargon. This skill
takes that exact artifact and makes it clear enough to act on: one decision
at a time, jargon defined, and the actual choices pulled to the surface.

The move is clarify by restructuring, never by simplifying. The content stays
at full precision and full reading level; only its arrangement changes. Lowering
the altitude is a different job, and turning the thing into a picture is a third
one (see Boundaries). A clarification that loses or softens a decision is
worse than the wall of text, so the fidelity rules below are hard, not aspirational.

The core move

1. Identify the target. With an argument, that is the thing. Empty
   argument → the previous assistant response (see Empty argument).
   Done when you can name the target, or, on a cold start, have asked what
   to clarify instead of inventing one.
2. Ground it, don't recall it. Re-read the actual artifact this turn, the
   message just sent, in full. Working from your memory of it instead of its text
   is how operative terms drift.
   Done when you have re-read the full target this turn and can quote an
   operative term from its text.
3. Restructure faithfully. Chunk, define jargon, surface decisions
   (below), under the fidelity rules.
   Done when every decision from the target appears in the restructured
   view and every omission is named. A paraphrase that drops or softens a
   decision is not done.
4. Choose the medium. Artifact, local file, or terminal, per
   Rendering.
   Done when the output is on the rendering ladder the table names for this
   session and content size, and you have not claimed an artifact that was
   not produced.

Empty argument, anaphora default

With no argument, the target is the assistant's own previous response, the
thing the reader is reacting to. "Make this clear" needs no topic named:
re-read that prior message and clarify it. When there is no prior assistant
message, a cold start where the reader opens with "make this clear" and
nothing has been said, do not invent a target: ask what to clarify.

Trivial-target escape hatch. When the resolved target holds fewer than ~2
decisions, a short answer, a status line, anything with nothing to untangle,
do not run the full table/glossary apparatus on it. Say in one line that
the target has nothing dense to clarify, and ask what the reader actually
wanted clarified. A three-line response restructured into a one-row decision
table is ceremony, not clarity.

Conflicting-shaper note. If a terse-for-tokens output shaper (e.g. caveman
hooks) is active in the session context, say so before rendering: this skill's
faithful, structure-adding output directly contradicts a strip-words directive,
and the two cannot both govern the same response. Advisory only. Name the
source and let the user pick.

Fidelity rules (hard)

A clarification is a lens on the original, not a replacement for it. These
four rules are non-negotiable, because a restructure that corrupts a decision
defeats the purpose:

1. Quote operative terms verbatim. The load-bearing words of every
   recommendation, the chosen option, the number, the named file, the
   condition, the verb that decides, are copied, never paraphrased. Restate
   surrounding framing in your own words if it helps; never the terms the reader
   will act on. "Go with option B, patch bump, gated behind --force" survives
   into the clarified version character-for-character.
2. Keep the original numbers as back-links. Every chunk carries the
   original item's own identifier (Q9, Round 4 · P15b, §3) so the reader can jump
   back to the source. This is separate from any numbering this skill adds for
   itself (see Rendering). Never collapse the two.
   When the original carries no identifiers (a dense prose memo with no Q-numbers
   or section marks), synthesize a locator and say you did: a sequential marker
   ("¶2", "Para 3") or the chunk's quoted opening phrase. Never leave a chunk
   with no way back to its source passage.
3. List omissions explicitly. Anything in the original you did not carry
   forward is named in a short "Left
   out" note, not silently dropped. That includes a caveat, a fifth option, a
   dependency. The reader decides whether an omission
   mattered; you do not get to decide it for them by hiding it.
4. State that it is a lens. Close with one line: this is a clarification.
   Validate final answers against the original text, not against this
   restructuring.

Restructure moves

Chunk into one decision at a time

Split the artifact so each chunk holds exactly one thing the reader
resolves. A round of seven bundled questions becomes seven chunks. No chunk
hides a second "and also decide." Order chunks so a prerequisite decision comes
before the one that depends on it, and say so when it does.

Define the session's own jargon

A dense artifact leans on shorthand coined earlier in the session, such as "the lane,"
"gate vacuity," "managed components," "P15b." Collect every such term and define
it once, in plain words, in a short glossary the reader can see while reading the
chunks (not one they must remember from earlier). Define the shorthand; do
not simplify the concept it names. The definition is a pointer to the term,
at the same altitude.

Surface what must be decided

For each chunk, make the actual choice unmissable: the recommendation (verbatim),
its Basis: (verbatim), the alternative it was chosen over (verbatim, if the
original named one), and, in one sentence, what the reader is actually
deciding, the crux, not a restatement of the option. If the original only
recommends with no alternative, say so rather than inventing one.

Carry the Basis: through unchanged: "none stated" when the source gave none, never
an inferred one. The label has three outcomes: Basis: verified with the
file:line, tool output, or URL behind it; Basis: judgment, allowed only for a
recommendation that is not consequential (cross-repo, shared infrastructure,
irreversible, or security); or withheld, where the source raised an unsettled
consequential choice as an open question instead of recommending. A withheld item
renders as "withheld" in the Recommendation cell with the evidence that would settle
it in the Basis cell, never with a recommendation invented for it; a recommendation
the source re-stated as old → new → why keeps all three parts. Full convention:
recommendation-basis.

Rendering: artifact-forward

Decision-dense content wants a table, not a paragraph. A table is the part a
plain reply cannot do well. Pick the medium by what the session can render and
how heavy the content is:

Content	Surface available	Render as
Big / decision-dense (roughly 3+ decisions)	Artifact tool present in this session	Published HTML artifact
Big / decision-dense	No artifact surface (e.g. plain terminal), file writing useful	Local HTML file under plugin data / temp, hand back the path
Small (1–2 decisions), or no useful file surface	either	Structured terminal markdown

The Artifact rendering surface is a claude.ai-hosted capability, present in some
sessions and absent in others. Detect it: if the Artifact tool is available, that
is the top rung; otherwise degrade down the ladder. Never claim a decision table
was rendered when only prose was produced.

Write any local HTML file to the ephemeral tier, one file created through
the platform's temp API, and hand back that path. A clarified view is
transient generated state, so it never lands in the consumer's repository tree.
Do not delete the file before returning: the path is the delivery
mechanism, so it must still be readable when the reader opens it. It outlives
this invocation, and nothing documented reclaims the OS temp tree on a
schedule, so write one file per run and never an accumulating tree. Resolve
that one path deterministically: never
branch on whether the harness injected a scratchpad path or set
CLAUDE_JOB_DIR, and never depend on the session scratchpad, which is
undocumented. Do not rely on a
plugin-data substitution variable for this location either: skill-body
substitution is documented only for a fixed set of variables, and an
undocumented token can substitute unpredictably (including to the wrong
plugin's directory when the token travels through another skill's arguments).
If no writable temp location nor the Artifact surface is available, drop to the
terminal-markdown rung rather than writing into the repo.

The fidelity rules hold in every medium. Verbatim terms, original-number
back-links, omissions, lens line, table or prose.

The decision table

Whichever medium, the decision table has numbered rows and these columns:

#	Item	Recommendation	Basis	Alternative	What you're deciding
1	Q9	(verbatim operative terms)	(verbatim, or "none stated")	(verbatim, or "none offered")	the crux in one sentence
2	Q10	(verbatim)	(verbatim)	(verbatim)	…

• The # column is the table's own row number (this skill's). Its job is
  answer-mapping, so the reader can reply "row 2: take the alternative" and you
  know exactly which original item that resolves.
• The Item column is the original identifier (Q9, §3, Round 4 · P15b), the
  back-link to the source. Two numbering systems, kept distinct.
• Recommendation, Basis, and Alternative cells carry the verbatim operative terms. A
  cell is where paraphrase and truncation creep in; resist both. If a
  recommendation is too long for a cell, quote its operative clause verbatim and
  link the row to the fuller original by its Item number. Never a lossy summary.
• The rendered-views security baseline governs the artifact and local-file
  media. The baseline is owned by docs/conventions/rendered-views/README.md
  ("Security baseline") in the marketplace repository; its rules are repeated
  here because this skill runs where that file is not on disk. Everything copied
  into the page is untrusted data: escape &, <, >, ", and ' in text
  and attribute positions; never interpolate unescaped content into <script>
  or <style>; never build an event-handler attribute from input. The page is
  self-contained: no external requests, no remote scripts, assets inline.
  Specific to this skill: operative terms often carry code-like characters
  (<dialog>, A && B, --force), so the escape rule is also what keeps rule
  1's verbatim promise true in the rendered page. In terminal markdown, wrap
  such terms in backticks so they render literally.

Honoring the Artifact contract

When you publish an artifact, honor the Artifact tool contract. Load the
artifact-design skill for the design fundamentals when it is available. It
ships with the artifact surface, so it is normally present on the publish rung;
if it is not, meet the contract's essentials directly rather than skipping them:
a self-contained page (the baseline above), theme-aware, a title and one-line
description, a favicon. Either way, the decision table is the page's spine. Keep
the treatment utilitarian, and this static table needs no runtime capabilities.
Leave out a hero banner, a cream or off-white background, italic accent words in
headings, numbered "01 / 02 / 03" section labels (the # column is the only
numbering), and pill-shaped badges, plus any style the reader names; when the
reader dislikes a choice in the page, add it to that list and render again. In the terminal, give a one-line summary and the artifact
link (or the local file path); don't reprint the whole table twice.

Boundaries

vs education:explain, structure, not altitude. explain drops the
altitude: plain words, a concrete analogy. It trades precision for
accessibility, and it climbs back up only on request. This skill holds altitude
fixed and changes arrangement: same precision, same reading level, made
clear by reorganizing.

vs education:eli5, structure, not medium. eli5 changes what the
explanation is: a visual explainer that assumes zero prior knowledge, one idea
per diagram, minimal text. Its floor does not climb the way explain's does. This
skill stays in the artifact's own medium and its own words.

The three-way routing rule: "I don't get it / explain simply / what does this
mean" is a comprehension gap → explain; "ELI5 / draw me this / show me a
diagram" is a request for a picture → eli5; "make this clear / clarify this /
what am I deciding" is a structure problem → this skill. For the first two, hand
off by invoking /education:explain or /education:eli5 via the Skill tool (if
the education plugin is installed, which owns both altitude and medium as
concerns); when it is not, say which of the two the ask actually wants and give a
faithful restructure, which is this skill's own job either way.

vs adhd:shape, one-shot, not standing. shape is a standing posture:
invoke it once and every response for the rest of the session is shaped. This is
a one-shot reshape of one artifact already on screen. It does not change
how future responses are written. Use shape to set the house style; use this to
rescue a specific wall of text. Two interaction rules when both are active:
the decision table is exempt from shape's five-item list cap (fidelity
forbids dropping decisions, and fidelity wins over shaping); and when the
target is shape-formatted output, judge by the target's actual decision
density, never its provenance. An already action-shaped, low-density
response has nothing left to restructure (take the trivial-target escape
hatch), but a dense multi-decision artifact still gets the full faithful
restructure even though shape produced it (shape's explain override emits
long, decision-heavy responses with no glossary, locators, or table).

Gotchas

• Clarifying is not summarizing. A summary drops detail to save length; this
  keeps every decision and rearranges it. If the reader ends up with fewer
  decisions than the original held, that is a fidelity-rule-3 omission you failed
  to declare.
• Verbatim means verbatim. The temptation to "clean up" a recommendation into
  a tidy cell is exactly the corruption the fidelity rules exist to stop. Copy the
  operative terms.
• Don't lower the altitude to fit the table. A cramped cell is a reason to
  quote the operative clause and link out, never a license to simplify the
  content. Simplifying is explain's job, not this one.

What this skill does NOT do

• Not a simplifier. Altitude stays fixed. Lowering it is
  education:explain.
• Not a picture. Medium stays fixed too. A diagram or an ELI5-style visual
  explainer is education:eli5.
• Not a summarizer. It keeps every decision; it does not compress the artifact
  to its gist.
• Not a standing output posture. It reshapes one artifact once; the
  session-wide shaper is adhd:shape.
• Not an input-capture form. It renders a clarified view to read and answer
  from; collecting answers through an artifact form is a deferred, separate
  capability.