# Clarify

> Faithfully clarify a dense, decision-heavy message so you can act on it. Chunk it into one-decision-at-a-time, define the session's own jargon, and surface exactly what you must decide, with operative terms quoted verbatim and no loss of precision. Decision-dense content gets an HTML decision table with numbered rows. Use when: 'make this clear', 'clarify this', 'help me digest this', 'break this down', 'I can't parse this', 'what am I actually deciding here', 'this is a wall of text'. Empty argument targets the previous assistant response. This changes STRUCTURE, not altitude and not medium. A lossy plain-language drop is education:explain (if installed) instead; a picture explainer (a diagram, ELI5) is education:eli5 (if installed). Sibling to adhd:shape, a standing session-wide posture; this is a one-shot reshape of one artifact.

- Skill: `melodic-software/clarify` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add melodic-software/clarify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/clarify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: melodic-software (https://skillmd.com/u/melodic-software)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/melodic-software/clarify

---


# 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](#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](#empty-argument-anaphora-default)).
   **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](#rendering-artifact-forward).
   **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](#rendering-artifact-forward)). 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),
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.

## 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 | Alternative | What you're deciding |
|---|------|----------------|-------------|----------------------|
| 1 | Q9 | *(verbatim operative terms)* | *(verbatim, or "none offered")* | the crux in one sentence |
| 2 | Q10 | *(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 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 <!-- contract-restatement-begin: rendered-views-security-baseline -->
  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. <!-- contract-restatement-end: rendered-views-security-baseline -->
  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, not a flashy hero, and this static table needs no
runtime capabilities. 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.