Command Refine

Quick Start

If user said "no" or "wrong": Analyze what went wrong → Output refinements → Prevent recurrence

If command failed: Check injection patterns → Identify root cause → Fix @/!

If files provided: Analyze alongside conversation → Cross-reference findings

Why: Meta-analysis turns corrections into prevention—every mistake becomes a rule.

Navigation

PATTERN: Conversation Analysis

What to Look For

Conversation-First Analysis

The conversation IS your primary input. No file reads needed for context.

When @files provided:

• Read injected content for additional context
• Cross-reference with conversation
• Synthesize findings from both sources

When no @files:

• Conversation alone is sufficient

Analysis Format

Each finding MUST have:

**Issue:** One-line description
**Evidence:** Quote from conversation or @file
**Root Cause:** Why it happened (not just symptoms)
**Fix:** Specific change to apply

Example

**Issue:** @path file may not exist
**Evidence:** User said "No" when command referenced missing file
**Root Cause:** No fallback for missing file
**Fix:** Add "(if exists)" handling after @path

PATTERN: Issue Classification

Classification Matrix

Severity Levels

PATTERN: Refinement Output

Concrete Changes Format

File: path/to/command.md Section: ## PATTERN: X Change: [Specific edit to apply] Why: [Reason for change]

Verification Checklist

1. Read the actual file
2. Apply the change
3. Verify no regressions
4. Test with similar conversation pattern

Output Template

## Refinement 1: [Title]

**File:** `.claude/commands/command-name.md`
**Section:** `## PATTERN: [Name]`
**Current:** [What exists]
**Change:** [What to add/replace]
**Why:** [Reason]

## Refinement 2: [Title]
...

PATTERN: Injection Refinement

@ Path Fixes

! Command Fixes

Argument Fixes

ANTI-PATTERN: Lazy Analysis

Anti-Pattern: Vague Findings

❌ Wrong:
"The command has issues"

✅ Correct:
"Line 45: @.claude/missing/file.yaml - path may not exist.
Root cause: No fallback handling.
Fix: Add '(if exists)' after @path."

Strong language: BE SPECIFIC. Vague findings = lazy analysis.

Anti-Pattern: Symptom-Only Reports

❌ Wrong:
"Command didn't work"

✅ Correct:
"User said 'No' at line 52.
Issue: !`rm *.log` is destructive.
Root cause: Unsafe ! command used.
Fix: Replace with !`ls *.log | wc -l`"

Anti-Pattern: No Evidence

❌ Wrong:
"The injection needs fixing"

✅ Correct:
"Command failed when @file was missing.
Evidence: 'No such file' error at line 23.
Fix: Add fallback handling after @path."

Anti-Pattern: Missing Root Cause

❌ Wrong:
"Fix the ! command"

✅ Correct:
"!`rm *.log` is destructive (line 41).
Impact: Deletes files without confirmation.
Fix: Use read-only !`ls *.log | wc -l`"

PATTERN: Verification

Before Publishing Refinements

Verification Commands

1. Read target command file
2. Apply refinement
3. Run: `mcp__ide__getDiagnostics`
4. Verify: No errors
5. Test: Does this prevent the original issue?

EDGE: Multiple Issues

Prioritization

When conversation has multiple problems:

1. Critical first — Security, destructive operations
2. High frequency next — Most common issues
3. Group related — Single fix for multiple occurrences

Batch Output

## Refinements (Priority Order)

### 1. CRITICAL: [Issue Title]
[Evidence] → [Root Cause] → [Fix]

### 2. HIGH: [Issue Title]
[Evidence] → [Root Cause] → [Fix]

### 3. MEDIUM: [Issue Title]
...

EDGE: No Issues Found

When Analysis Yields Nothing

## Analysis Result: No Issues Detected

**What happened:** Command executed without corrections
**What this means:** Commands working as intended

**If this is wrong:**
- User may have silently accepted poor output
- Check for injection patterns that may fail edge cases
- Review ! commands for potential safety issues

EDGE: Injection-Specific Checks

When Analyzing @ Paths

• Path exists? If not, add fallback
• Content dynamic? Static content doesn't need @
• Wrapper used? Prefer <injected_content> grouping
• Error handling? Missing files handled gracefully

When Analyzing ! Commands

• Read-only? No destructive operations
• Safe? No rm, git push --force, chmod
• Error handling? Failed commands don't crash
• Simple? Complex logic in scripts, not inline

When Analyzing Arguments

• $1 for IDs only? Not flags/options
• Pattern consistent? ID/slug/hash format
• Fallback present? $IF($1, ..., ...) for optional

Recognition Questions

PATTERN: Quick Refinement Checklist

Validation Checklist

Before claiming command refinement complete:

Analysis Quality:

• Evidence provided for every finding (conversation quote or file reference)
• Root cause analyzed, not just surface symptoms
• Fix is concrete (file + section + specific change)
• No false positives flagged
• No vague findings or assumptions

Injection Safety:

• All @ paths have fallback handling ("(if exists)")
• All ! commands are read-only (no rm, --force, etc.)
• Missing files handled gracefully
• Destructive commands replaced with safe alternatives

Classification:

• Issue correctly classified (@ issue, ! issue, description, etc.)
• Severity level assigned appropriately (CRITICAL/HIGH/MEDIUM/LOW)
• Target file and section identified correctly

Output Format:

• Concrete changes format used (File/Section/Change/Why)
• Language appropriate (strong for failures, positive for correct)
• Multiple issues prioritized (Critical first)

Verification:

• Actual file read before applying changes
• Diagnostics run after changes
• Fix prevents original issue (verified)

Common Mistakes to Avoid

Mistake 1: Vague Findings Without Evidence

❌ Wrong: "The command description needs improvement."

✅ Correct: Issue: Missing 'Not for' exclusion in description Evidence: User said "No" when skill triggered for unrelated task Root Cause: Description triggers too broad, includes unintended use cases Fix: Add "Not for X" to description frontmatter at line 3

Mistake 2: Skipping Root Cause Analysis

❌ Wrong: "The @ path is wrong. Fix it."

✅ Correct: Issue: @ path uses relative path that fails when invoked from different directory Evidence: Command fails with "File not found" error Root Cause: Path is relative to workspace root but command runs from project root Fix: Change @./docs/page.md to @/Users/project/docs/page.md

Mistake 3: Missing File Verification

❌ Wrong: "Fix the frontmatter" (without reading the file)

✅ Correct: Issue: Frontmatter missing 'model' field Evidence: Read skill/SKILL.md lines 1-5 Fix: Add model: inherit to frontmatter

Mistake 4: Dangerous ! Commands

❌ Wrong:

!`rm -rf node_modules && npm install`

✅ Correct:

!`npm list --depth=0`

(Use read-only commands in ! patterns)

Mistake 5: No Severity Classification

❌ Wrong: "The skill needs improvement."

✅ Correct: Issue: Missing portability invariant (CRITICAL) Root Cause: Skill references project rules (CLAUDE.md, CLAUDE.local.md, or .claude/rules/) Fix: Remove all project rules references, bundle philosophy in file

Best Practices Summary

✅ DO:

• Quote specific evidence from conversation or files
• Analyze root cause, not just symptoms
• Ensure all @ paths have fallback handling
• Ensure all ! commands are read-only (no destructive operations)
• Use strong language for destructive command issues
• Specify exact file, section, and change for each fix
• Verify changes against actual files

❌ DON'T:

• Make vague findings ("The command has issues")
• Use destructive ! commands (rm, --force, chmod)
• Skip fallback handling for @ paths that may not exist
• Report symptoms without root cause analysis
• Skip evidence (every finding must have a quote)
• Use weak language for safety issues
• Skip diagnostics after applying changes

1. Conversation is PRIMARY input (already in context)
2. @files are OPTIONAL supplements
3. Output MUST be concrete (not vague recommendations)
4. Every finding MUST have evidence
5. Fixes MUST specify exact file and section
6. Strong language for agent failures
7. Verify everything against actual files
8. All ! commands MUST be read-only
9. All @ paths MUST have graceful fallback
10. Never use relative paths pointing outside the skill itself. When referencing other components, use: "invoke skill-name" or "invoke skill-name and read its file"

NO VAGUE FINDINGS. NO DESTRUCTIVE COMMANDS. BE SPECIFIC.