Hands-on guides for Claude Code and Codex
Three ways to use Clarity.
Start with a draft you care about. Clarity can review it without touching the file, rewrite it while protecting the source, or interview you when the draft needs material only you can supply. These tutorials use the same small example so you can see where the agent works and where you make the call.
Setup
Install the skill once
Run the installer in a terminal, then open Claude Code or Codex in the directory that contains your draft.
/clarity interviewit interviews you, then co-writes from what you said/clarity rewriteit edits a draft you already have/clarity reviewit critiques and leaves your file alone
The examples use /clarity in Claude Code and $clarity in
Codex. If your agent does not expose a command shortcut, ask it in plain language to
use the clarity skill in review mode
. The mode and file path matter more than
the shortcut.
Our starting draft
Save this as incident-reviews.md, or use one of your own drafts. This
example is grammatical and empty in a familiar way. It gives the skill something real
to diagnose without pretending that a list of banned words is the whole problem.
# Why incident reviews matter
Incident reviews play a crucial role in modern engineering teams.
They provide valuable insights and help organisations learn from failure.
By fostering a culture of continuous improvement, teams can leverage
these reviews to build more resilient systems.
Ultimately, incident reviews are not just about looking back. They are
about creating a stronger and more collaborative future.01
Review
Find the real problems without changing the draft
Use review mode when you want a diagnosis before deciding what should change. The source file stays untouched.
Run it
In Claude Code:
/clarity review incident-reviews.mdIn Codex:
$clarity Review incident-reviews.md. Do not modify the file.Clarity first identifies the job of the piece, its reader, and the largest material problem. It then reports only the passages worth your attention. An illustrative part of the response might look like this:
Job: Short article for engineering managers
Substance: The draft says reviews help, but contains no incident,
mechanism, or decision that changed because of one.
Top fixes: 1. Add the event that triggered the piece.
2. Replace the generic benefit with what changed afterward.
Passage: "Incident reviews play a crucial role..."
Verdict: ask-author
Pattern: Importance without mechanism
Suggestion: Which review changed a decision, owner, or system?
Safety check: Needs author evidence. Do not invent the incident.Your turn
The human decision happens before the edit
ask-author means the model has reached the edge of the source. Answer with
the detail you are comfortable publishing, reject the question, or choose the plain
fallback. For example:
The trigger was three incident reviews in one quarter that all ended
with "improve monitoring." The third review changed when Priya asked
who would be paged if the same cache failed again. Keep this as a
review. Update the findings, but do not edit the file.
Review mode remains a conversation. You can ask why a passage was marked
revise, keep a sentence the skill questioned, or stop after the first two
fixes. Nothing is applied until you ask for a separate rewrite.
02
Rewrite
Improve the draft while keeping its claims intact
Use rewrite mode when the source has enough material and you want the agent to edit the named file. Give it the facts and phrases that must survive.
Prepare
Put the draft in version control or make a copy first. A diff is the quickest way to catch a stronger claim, a lost qualifier, or a sentence that no longer sounds like you.
git status --short
git diff -- incident-reviews.mdAdd the specific material from the review to the draft, or include it in your request. Then name the constraints:
/clarity rewrite incident-reviews.md
The reader is an engineering manager. Preserve the phrase "the review
became a status meeting," the date, Priya's quoted question, and every
link. If a stronger claim needs information outside the draft, ask me.In Codex, the same request begins with $clarity Rewrite.
Inspect
Read the diff as an editor
For a named file, Clarity writes the finished prose to the file and reports a short change note in chat. It may leave a question where the honest edit needs a number, example, or decision that the source does not contain.
git diff --word-diff -- incident-reviews.mdCheck four things before accepting the pass:
- Dates, numbers, quotations, links, and attribution kept the same force.
- A possible result did not become a guaranteed one.
- The useful line you would have kept was not polished flat.
- The ending stops when the concrete consequence ends.
Your turn
Make the final corrections narrow
Answer open questions and protect any sentence the diff weakened. A useful follow-up names exactly what the agent may change:
The number was 11 reviews, not 12. Restore "the review became a status
meeting" exactly as written. Apply only those two changes, then stop.Repeated polishing passes tend to converge on the same smooth voice. One rewrite, one source check, and one small correction pass is usually enough.
03
Interview
Put the missing author back into a hollow draft
Use interview mode when surface editing would produce cleaner emptiness. The agent waits for your material before it writes.
Begin
Give Clarity the topic and tell it that the existing file is background, not a set of instructions. Ask it to wait:
/clarity interview Why our incident reviews stopped working
Use incident-reviews.md as background. Interview me before drafting.
Keep the existing file unchanged.In Codex:
$clarity Interview me about why our incident reviews stopped working.
Read incident-reviews.md as background, but do not rewrite it yet.The first response should invite one untidied answer. Talk for three to five minutes, paste a rough transcript, or stream-type without organising it first. You do not need to answer a polished questionnaire.
We ran 11 reviews before I noticed the pattern. The meeting had become
a status update for leadership. Priya interrupted the third cache
incident and asked, "Who gets paged next time?" Nobody could answer.
That was the moment the review became useful again...Follow up
Expect a few questions, not a substitute autobiography
Clarity may ask up to three questions about unsupported parts of the draft. Good questions locate a specific gap: what changed after Priya's question, what you would concede to someone who prefers status reviews, or what the reader should do on Monday.
Skip anything private. A plain omission is better than a blurred anecdote. The skill
should leave [TK: precise question] when the piece still needs a fact only
you have.
Use my answers to draft incident-reviews.interview.md. Keep the original
file. Preserve Priya's question verbatim. Show me any larger rewording
that changes the thought instead of silently applying it.Your turn
The provenance note is part of the handoff
The draft should be followed in chat by a short account of where its material came from. This is more useful than a detector percentage because you can inspect the process it describes.
Author material: The 11 reviews, the cache incident, Priya's question,
and the distinction between a review and a status meeting.
Model contribution: Organisation and connective prose.
Open items: [TK: what changed in the on-call runbook afterward?]Read the new draft beside your transcript. Keep the phrases that still sound like the moment you described. Answer the open item if it matters, or cut the sentence that needs it.
Next
Which mode should you start with?
- Start with review when you want to understand the draft before changing it.
- Use rewrite when the source is sound and you are ready to inspect an edit.
- Choose interview when the draft lacks your examples, judgment, or language.
You can move between them. A review may reveal that the draft needs an interview. An interview-built draft can go through one rewrite after you have checked its source. Keep the mode explicit and the next decision stays easy to see.