clarify

A Claude Code skill that runs a relentless, concept-by-concept clarity pass on a piece of writing. It interviews you to resolve what you actually meant before proposing minimal edits. The goal is not to polish prose, it is to extract the underlying argument and force each concept to be sharp.

Why

Clear writing comes from one habit: holding high standards for clarity (cit. Paul Graham). You notice when something is unclear, ask what you actually meant, fix it, and repeat. A first draft is a muddy pool; clarifying it is the work of deciding not just what to say but what you mean.

The catch is that the whole loop depends on noticing your own unclear thinking, which is exactly the thing you are worst at seeing in your own draft. This skill runs that loop for you. It hunts down every muddy spot, separates the ones it can resolve from references from the ones only you can answer, interviews you on those, and turns the result into the smallest edits that make the meaning sharp. You keep the high standards; it does the noticing.

How I use it

Point it at an existing draft, a blog post, or a transcript of a brainstorming session where you dictated what you were trying to expand on. You can point it at your Obsidian vault, prior posts, the codebase it describes, or any other references you want it to use to ground itself as it maps out all the concepts and helps you flesh out what you are saying.

The flow is three stages:

1. Scan (workflows/clarify-scan.js): heavy parallel analysis, run as five phases (you can watch them fan out in /workflows):

   1. Decompose: segment the draft, then fan out one agent per section to extract every atomic concept and claim, each tagged clear, muddy, ambiguous, or unsupported.
   2. Tree: one strong agent reconciles those local views into a single dependency graph and topologically sorts it, foundations first. This ordering is the part that makes the method work, because a concept can only be clarified after the ones it rests on.
   3. Classify: for each unclear node, decide where its answer lives, the draft, your corpus, the code, the web, or genuinely only you.
   4. Resolve: fan out read-only explorers to settle everything that is not yours to answer, building the intent ledger. Anything they cannot ground in evidence gets handed back to you.
   5. Rank: assemble the questions only you can answer, each phrased confirm-or-correct with a recommended answer and its evidence, ordered foundations first then by clarity impact, capped so you are never buried.

   Cheap fan-out (decompose, classify, resolve) runs on a fast model; the two reasoning phases (tree, rank) run on the strongest one.

2. Interview (conversational, in the session): walks the scan's questions one at a time, leading with a recommended answer and its evidence so you confirm or correct rather than start from scratch.

3. Edit (workflows/clarify-edit.js): takes the answered ledger, generates minimal candidate edits, filters them by rubric, has a separate agent adversarially verify each one, and emits proposed edits for review.

See SKILL.md for the full procedure and references/method-and-rubrics.md for how clarity is judged and questions are ordered.

Requirements

This relies on Claude Code's dynamic workflow runtime, which supplies the agent-spawn primitive and regenerates the runnable scripts from the templates in workflows/ at launch. Workflows are a research preview.

• Tested on Claude Code version 2.1.161.
• Workflows article: https://x.com/trq212/status/2061907337154367865
• Workflows docs: https://code.claude.com/docs/en/workflows

The two files in workflows/ are templates, not verbatim scripts. What matters is the orchestration: the phases, the structured-output shapes, the model routing, and the args contract. If you have a scan or edit script that already worked, saved via s in /workflows, drop it in over the template.

Install

Clone into your Claude Code skills directory:

git clone git@github.com:JayFarei/clarify.git ~/.claude/skills/clarify

Then invoke it in a session with /clarify, or just share a draft and ask to make it clearer.