Candid Improve

Where /candid-review and /candid-improve-implementation work on code, this skill works on any output you already have — marketing copy, documentation, an answer, a plan, a prompt, an email, a spec. It runs a critique → refine loop: name what’s weak against your goal, rewrite to fix it, repeat until the stop condition is met.

Quick Start

/candid-improve

With no arguments, it improves the last output in this session in a single pass, using the current context to decide what “better” means. Point it at a file or paste text to improve something else.

When to Use It

• You have a draft — copy, docs, an email, a plan — and want a sharper version
• An answer or explanation you just produced needs tightening
• A prompt or spec that isn’t landing the way you want
• Any text artifact where you can name a goal (“punchier”, “under 120 words”, “no jargon”)

Not the right tool for: reviewing code for defects (use /candid-review), a code-quality pass (use /candid-improve-implementation), or generating something from scratch (just ask).

How It Works

1. Resolve the target — --file <path>, inline text you paste, or (default) the most recent substantive output in the session. Ambiguous? It asks.
2. Resolve the goal — your --criteria/rubric, the surrounding context, or (default) an intent inferred from the session, stated back so you can correct it.
3. Resolve the destination — file source defaults to writing back (overwrite confirmed first); inline/session source prints to chat. Override with --out/--in-place.
4. Critique → refine loop — each cycle names weaknesses across the active lenses, then rewrites to address them, showing a before→after preview.
5. Stop — when the rubric is met, iterations are exhausted, the cycle converges, no progress is made, or --max-iterations is hit.
6. Save state — writes .candid/last-improve-output.json.

Critique Lenses

Each cycle critiques against the goal using these lenses (adapted to the artifact type; restrict the set via improveOutput.lenses):

• 🎯 Intent fit — does it actually satisfy the goal / answer the ask?
• 🧩 Completeness — missing pieces, unsupported claims, gaps?
• 🔍 Clarity — ambiguous, confusing, poorly ordered, jargon?
• ✂️ Concision — padding, redundancy, filler, hedging?
• 🎨 Craft — tone, correctness, rhythm, polish for the medium.

Stop Conditions

By default the loop runs exactly one pass. Opt into looping:

If --criteria is set it is the stop bar; else --until-converged loops to convergence; else iterations cycles run. All looping is capped by --max-iterations.

Modes

Mirror /candid-loop. Set with --mode or improveOutput.mode.

• auto (default) — accept every critique point and rewrite.
• review-each — per-point Yes/No before it’s applied (offers the rewrite as a preview).
• interactive — per-point Apply / Skip / Edit-the-goal / Stop-all.

Flags

Examples

# Refine the last session output, single pass
/candid-improve
 
# Two cycles on a file
/candid-improve --file README.md --iterations 2
 
# Loop until it hits the bar
/candid-improve --until-converged --criteria "punchier, under 120 words, active voice"
 
# Step through each critique point on a draft
/candid-improve --mode interactive --file pitch.md
 
# Blunt tone, concrete criteria, overwrite the source
/candid-improve --harsh --file draft.md --in-place --criteria "no marketing fluff, concrete claims only"

Configuration

Add to .candid/config.json:

{
  "tone": "constructive",
  "improveOutput": {
    "mode": "auto",
    "iterations": 1,
    "maxIterations": 5,
    "lenses": ["intent", "completeness", "clarity", "concision", "craft"],
    "defaultDestination": "chat"
  }
}

The improveOutput block is deliberately separate from /candid-improve-implementation’s improve block — different jobs, no shared config or state. tone is shared with /candid-review.

See Also

• Candid Review — defect / risk / security review of code
• Candid Improve Implementation — code-quality pass on working code
• Candid Loop — fix-review-fix loop for code