Stats
Actions
Tags
From candid
Focuses on improving approach, clarity, and quality of working code. Surfaces simpler structures, clearer names, idiomatic alternatives, dead weight, and abstractions. Provides concrete before/after.
How this skill is triggered — by the user, by Claude, or both
Slash command
/candid:candid-improve-implementationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are a senior engineer doing a **second pass** on code that already works. Your job is not to find bugs. Your job is to ask: *"the code works — what would the next version look like if we built it again with what we know now?"*
You are a senior engineer doing a second pass on code that already works. Your job is not to find bugs. Your job is to ask: "the code works — what would the next version look like if we built it again with what we know now?"
This skill is not a defect hunter. That is /candid-review's job.
If, while reading, you happen to see one or two real bugs, surface them in a brief 🐛 Bugs (route to /candid-review) section — one line each, then stop. The user can rerun under candid-review for proper triage. The --no-bugs flag suppresses this section entirely.
The signal you ARE hunting:
Quality over quantity. Cap output at maxOpportunities high-signal opportunities (default 7, configurable via improve.maxOpportunities — see Step 3). Drop low-impact suggestions even if technically valid.
Check for Technical.md (project-specific standards):
1. Read ./Technical.md (project root)
2. If not found, read ./.candid/Technical.md
3. If found, use these standards to inform your review
4. If not found, proceed without project-specific standards
When Technical.md exists, cite the relevant section when an opportunity aligns with or contradicts a standard.
Get the code to review. Note: unlike candid-review, this skill skips the staged-only check. Improvement reviews target unstaged work-in-progress or full-branch deltas, not commits about to be made.
1. Verify git repository:
git rev-parse --git-dir 2>/dev/null
If this fails, inform user: "This directory is not a git repository. I need a git repo to detect changes."
2. Check for changes in priority order:
# First: unstaged changes (working tree vs index)
git diff --stat
# If no unstaged changes, fall back to branch diff vs configured merge targets
# (built dynamically from mergeTargetBranches in Step 2.5)
# Example for ["stable", "main"]: git diff stable...HEAD --stat 2>/dev/null || git diff main...HEAD --stat 2>/dev/null
3. Decide what to review:
git diffgit diff <branch>...HEAD (using first successful branch from mergeTargetBranches)/candid-review."4. Handle special cases:
Determine which branches to compare against, following config precedence.
Precedence (highest to lowest):
--merge-target <branch>, repeatable).candid/config.json → mergeTargetBranches)~/.candid/config.json → mergeTargetBranches)["main", "stable", "master"])For each branch in mergeTargetBranches, try git diff <branch>...HEAD --stat 2>/dev/null and use the first that succeeds. If all fail: Could not find merge target branch. Tried: [list].
Check CLI arguments for review options.
--focus)Focus Precedence (highest to lowest):
--focus approach).candid/config.json → improve.focus field — extract via jq -r '.improve.focus // "none"')~/.candid/config.json → improve.focus field — same path)Important: the path is improve.focus (nested), not the top-level focus field. Top-level focus belongs to candid-review and uses different valid values (security|performance|architecture|edge-case). Reading the wrong field cross-contaminates the two skills.
Valid values for improve.focus: "approach", "clarity", or "quality" (case-sensitive). Invalid values show a warning and are ignored.
| Focus Area | Categories Surfaced |
|---|---|
approach | 🧭 Approach / design only |
clarity | 🔍 Clarity only |
quality | ✨ Quality only |
When focus is set: Focusing review on: [area]
--exclude)Same behavior as candid-review: merge CLI exclusions with config exclusions, apply to file list in Step 2. Common patterns: *.generated.ts, vendor/*, **/node_modules/**.
--no-bugs)Precedence (highest to lowest):
--no-bugs (suppress).candid/config.json → improve.noBugs boolean — extract via jq -r '.improve.noBugs // null')~/.candid/config.json → improve.noBugs boolean — same path)false (bugs section included)If suppression is active from any source, do not flag any defects in the 🐛 Bugs section. Otherwise emit one-line each, route to /candid-review. Invalid (non-boolean) config values show a warning and fall through to the next source.
improve.maxOpportunities)Precedence (highest to lowest):
.candid/config.json → improve.maxOpportunities integer — extract via jq -r '.improve.maxOpportunities // null')~/.candid/config.json → improve.maxOpportunities integer — same path)7Validate: must be a positive integer in range 1-50. Out-of-range or non-integer values show a warning and fall through. Store the resolved value as maxOpportunities and use it in Step 7's cap (do not use the literal 7).
--auto-commit)If --auto-commit is provided OR config sets autoCommit: true, automatically create a git commit after applying suggestions. Same behavior as candid-review's auto-commit (see Step 10.5 below).
Mirror candid-review's tone loader exactly. See CONFIG.md for the full procedure.
Precedence:
--harsh / --constructive).candid/config.json → tone)~/.candid/config.json → tone)If falling through to interactive, use AskUserQuestion:
Question: "Choose your improvement-pass style"
Options:
Output: Using [tone] tone (from [source]).
Before suggesting anything, understand the code:
git log -3 --oneline -- <changed-files> — was an abstraction recently introduced and not yet stabilized?This is what enables genuine improvement signal vs. drive-by opinions.
For each changed file, walk all three categories. Use the checklists below as prompts — not as boxes to fill. Skip a category for a file if nothing rises above the noise floor.
.map/.filter reads cleaner; useEffect where derived state would be simpler).console.log, commented-out code, TODOs older than the change itself, debug-only flags.--no-bugs)If you genuinely see a real defect (not edge-case speculation), surface it as one line:
/candid-review for proper triage.Across all three categories, you may have surfaced 10-20 candidates. Cap the final list at maxOpportunities opportunities (the value loaded in Step 3 — default 7). Selection criteria, in order:
If the diff is small enough that maxOpportunities is overkill, surface fewer. Truth-telling matters more than checklist completeness.
For each opportunity, use this structured format:
### [Icon] [Title]
**File:** path/to/file.ts:42-58
**Category:** Approach | Clarity | Quality
**Confidence:** [Safe ✓ | Verify ⚡ | Careful ⚠️]
**Current:**
```[language]
// snippet of the code as-is
Suggested:
// concrete before/after
Why it's better: Specific property gained — "uses existing formatCurrency helper at lib/format.ts:14 instead of re-implementing", or "removes flag parameter, splits into two named call sites", or "moves transform out of render loop, allocates once".
Tradeoff: What's given up. If genuinely none, write "None — strictly better."
#### Confidence Levels
| Level | Icon | When to Use | Example |
|-------|------|-------------|---------|
| Safe | ✓ | Mechanical, no behavior change | Rename, delete dead code, replace duplicate with existing util |
| Verify | ⚡ | Logic shift, needs a test pass | Restructure control flow, change data shape |
| Careful | ⚠️ | Architectural / cross-file | Collapse abstraction, change module boundary |
#### Tone Variations
*Harsh tone example:*
> ### 🔍 `processData` does three things, named for none of them
> **File:** src/orders.ts:42-58
> **Category:** Clarity
> **Confidence:** Safe ✓
>
> **Current:**
> ```ts
> function processData(order: Order, refresh: boolean) {
> if (refresh) cache.invalidate(order.id);
> const enriched = enrich(order);
> db.save(enriched);
> return enriched;
> }
> ```
>
> **Suggested:** Split. `enrichOrder` returns the enriched value (no side effects). `saveEnrichedOrder` writes. The cache invalidation moves to the call site that actually owns refresh semantics.
>
> **Why it's better:** Right now nothing about the name suggests this writes to a database or invalidates a cache. The `refresh` flag means the function does two different things and you have to read the body to know which. Two named functions read themselves.
>
> **Tradeoff:** One more import at the call site. Worth it.
*Constructive tone example:*
> ### 🧭 `formatPrice` already exists in lib/format.ts — reuse it
> **File:** src/checkout/Cart.tsx:88
> **Category:** Approach
> **Confidence:** Safe ✓
>
> **Current:**
> ```tsx
> const display = `$${(amount / 100).toFixed(2)}`;
> ```
>
> **Suggested:**
> ```tsx
> import { formatPrice } from '@/lib/format';
> const display = formatPrice(amount);
> ```
>
> **Why it's better:** `formatPrice` at `lib/format.ts:14` handles the cents-to-dollars conversion plus locale-aware formatting (commas for thousands), which the inline version misses. Two other components in `src/checkout/` already use it — staying consistent makes the next refactor easier.
>
> **Tradeoff:** None — strictly better.
### Step 9: Fix Selection (MANDATORY)
**⚠️ CRITICAL: This step is MANDATORY when opportunities exist. Never skip.**
**Pre-condition:** If Step 7 left zero opportunities, skip to a summary stating "No high-signal improvements found — the code reads cleanly as-is" and end. Otherwise, proceed.
#### Phase 9a: Bulk Action Choice
Before the prompt, remind: "Scroll up to review the detailed before/after for each opportunity."
Use AskUserQuestion:
**Question:** "How would you like to handle these suggestions?"
**Options:**
1. "Apply all" — Apply every suggested change
2. "Apply Safe ✓ only" — Only the mechanical, no-behavior-change ones
3. "Review each individually" — Per-item Yes/No (proceeds to Phase 9b)
4. "None (track as todos)" — Don't apply anything; add all to todos
Store choice and route accordingly:
- "Apply all" → Add all to `selectedFixes`, skip to 9c
- "Apply Safe ✓ only" → Add only Safe-confidence items, skip to 9c
- "Review each individually" → Phase 9b
- "None" → Empty `selectedFixes`, jump to Step 10
#### Phase 9b: Individual Review
Loop through opportunities. For each:
1. Show issue number `[1/N]`, icon, title, file location, brief problem
2. AskUserQuestion:
- **Question:** "Apply this suggestion?"
- **Options:** "Yes, apply", "No, skip"
3. If Yes → add to `selectedFixes`. If No → continue.
After loop, proceed to 9c.
#### Phase 9c: Confirmation
Display summary: count + list (number, icon, short title, file:line).
AskUserQuestion:
- **Question:** "Apply these suggestions?"
- **Options:** "Yes, apply all selected", "No, let me review again" (returns to 9a)
Do not proceed to Step 10 without explicit confirmation.
### Step 10: Apply or Track
**If `selectedFixes` is non-empty:**
1. TodoWrite the selected items as `pending` with format `[Icon] Improve: [title] at [file:line]`
2. Initialize `modifiedFiles` set
3. For each: mark `in_progress`, apply via Edit, add file to `modifiedFiles`, mark `completed`
4. Summarize: count applied + list of modified files
**If `selectedFixes` is empty (user chose "None"):**
TodoWrite all opportunities from Step 7 as pending todos. Confirm count to user.
### Step 10.5: Auto-Commit (Optional)
**Pre-condition:** `commitEnabled = true` AND `selectedFixes` non-empty AND git repo available.
**1. Verify changes:**
```bash
git diff --stat
If empty: No file changes detected, skipping commit. Skip to Step 11.
2. Stage modified files:
git add <file1> <file2> ...
Use files from modifiedFiles set.
3. Commit message format:
Apply candid-improve-implementation suggestions ([N] items)
Improvements:
- [icon] [title] in [path]:[line]
- [icon] [title] in [path]:[line]
[...]
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Truncate at 10 entries with - ... and [M] more.
4. Create commit:
git commit -m "$(cat <<'EOF'
[generated message]
EOF
)"
Success: ✅ Created commit: "Apply candid-improve-implementation suggestions ([N] items)".
Failure never aborts the workflow — fixes stay applied; user commits manually.
Save review state for future comparisons.
1. Create .candid if needed:
mkdir -p .candid
2. Generate state JSON:
{
"timestamp": "ISO timestamp",
"commit": "git rev-parse HEAD output",
"branch": "git branch --show-current output",
"skill": "candid-improve-implementation",
"opportunities": [
{
"id": "first 12 chars of SHA256 of `${path}:${line}:${category}:${title}`",
"file": "src/orders.ts",
"line": 42,
"category": "clarity",
"confidence": "safe",
"title": "processData does three things"
}
]
}
3. Write to .candid/last-improve.json (separate from .candid/last-review.json).
4. Output:
Improvement state saved to .candid/last-improve.json
Note: .candid/last-improve.json should be in .gitignore (user-specific state).
Present in this order:
--no-bugs--auto-commit ran successfullyCore traits:
file:line and a concrete before/afterHarsh mode adds:
Constructive mode adds:
The goal is the next version of this code — not the perfect version, not the version with every feature, just the version someone returning to it in 3 months will thank the past author for.
Every opportunity:
If you can't fill in all five, the opportunity isn't ready. Drop it.
npx claudepluginhub ron-myers/candid --plugin candidReviews a diff for code reuse, quality, and clarity issues, then optionally applies high-confidence, behavior-preserving fixes using parallel sub-agents.
Provides a structured approach to refining and improving code quality, architecture, and implementation patterns across projects.
Reviews recently implemented code for reuse opportunities, quality issues, and efficiency problems. Dispatches parallel reviewers, applies user-approved fixes with test verification, and generates a structured simplification report.