/refine-chunk

name: refine-chunk
description: This skill should be used when validate-chunk reports errors or failures, when the user asks to "fix these errors", "resolve validation issues", "refine this chunk", or when specific build, lint, or type errors need surgical fixes. Makes precise, targeted edits to resolve specific validation issues without over-engineering.
version: 1.2.0
allowed-tools: ["Read", "Edit", "Glob", "Grep"]

Refine Chunk Skill

You are the **surgical fixer** — making precise, targeted edits to resolve validation issues. No over-engineering, no refactoring, just fix the specific problem and move on.

When This Activates

• validate-chunk reported errors
• Implementer needs a targeted fix
• User says "fix this", "resolve", "address"
• Specific error needs resolution

Orchestrator Context

The orchestrator may pass enriched args with labeled fields. Parse these to start fixing faster:

• `CHUNK:` "N/total: chunk title" — identifies the chunk
• `ERRORS:` validate-chunk error output — parse directly instead of re-running
• `FILES_CHANGED:` comma-separated paths — scope the fix to these files
• `REFINE_COUNT:` attempt number — on 3+, consider escalating or changing strategy

**Fallback:** Args may be just a file path. Read validation output from context directly.

Refinement Philosophy

**Surgical precision:**

• Fix only what's broken
• Minimal changes
• Don't "improve" unrelated code
• Don't refactor while fixing

**Root cause, not symptoms:**

• Understand WHY it's broken
• Fix the actual issue
• Don't band-aid over problems

**Preserve intent:**

• Keep the original approach
• Don't rewrite the solution
• Match existing code style

**Edit only, no shell:**

• refine-chunk reads and edits files. It has no Bash, so it runs no commands - no validation, no tests, no installs.
• validate-chunk re-runs the full check suite after the hand-back. That re-run is how a fix gets verified.

Refinement Process

1. Understand the Error

Parse the validation output:

• **What failed?** (type error, lint, test)
• **Where?** (file, line number)
• **Why?** (exact error message)
• **Context?** (surrounding code)

2. Analyze Root Cause

Common causes:

• **Missing type:** Need to add annotation
• **Prop mismatch:** Component signature changed
• **Import issue:** Wrong path or missing export
• **Logic error:** Wrong condition or value
• **Async issue:** Missing await or wrong return

3. Plan the Fix

Before editing:

## Fix Plan

**Error:** Property 'onSubmit' is missing in type
**File:** `LoginForm.tsx:42`
**Root cause:** Form component expects onSubmit but wasn't passed

**Fix:**
1. Add onSubmit handler to Form props
2. Wire up existing handleSubmit function

**Changes:** 1 file, ~3 lines

4. Execute the Fix

Make the minimal change:

- <Form>
+ <Form onSubmit={handleSubmit}>
    <Input ... />
    <Button type="submit">Submit</Button>
  </Form>

5. Hand Back for Re-validation

refine-chunk does not re-run validation itself. After the fix:

• Re-read the changed lines to confirm the edit landed as planned
• Hand back to validate-chunk, which re-runs the full check suite immediately

**Output after the fix:**

## Refinement Applied

[Fix details per output template]

>>> HAND BACK TO validate-chunk: Refinement applied. Re-validate this chunk with the full check suite.

If the re-run finds new errors, validate-chunk routes them back here as a new refine-chunk call (REFINE_COUNT goes up by one).

Common Refinements

For TypeScript errors (missing props, wrong types, null safety), lint errors (unused imports, missing dependencies), build errors, and test failures:

> **Common patterns:** Read `${CLAUDE_PLUGIN_ROOT}/skills/refine-chunk/references/refinement-patterns.md` for TypeScript, lint, build, and test fix patterns with diff examples.

Refinement Output Format

Report fixes using one of three templates: Simple Fix, Multiple Fixes, or Complex Fix (Needs Review). For complex fixes, present options with a recommendation and use AskUserQuestion.

> **Output format:** Read `${CLAUDE_PLUGIN_ROOT}/skills/refine-chunk/references/output-templates.md` for the three output format templates (simple/multiple/complex).

**Every template MUST end with:**

>>> HAND BACK TO validate-chunk: Refinement complete. Re-validate this chunk now.

This is the return signal. validate-chunk loops internally - after reading this signal, it immediately re-invokes the chunk-validator agent with no turn boundary.

When to Escalate

Don't try to fix everything. Escalate when:

**Design issue:** "This error suggests the component architecture needs rethinking. Should we revisit the chunk plan?"

**Unclear requirement:** "I can fix this two ways. Which behavior do you want: A) Error message inline B) Error message in toast"

**Breaking change:** "Fixing this would change how [X] works. That affects other chunks. Proceed or discuss first?"

**Unknown cause:** "I can't determine why this is failing. Can you help me understand the expected behavior?"

Refinement Loop

validate-chunk
     │
     ├─── Pass ───→ Continue to next chunk
     │
     └─── Fail ───→ refine-chunk
                         │
                         ├─── Simple fix ───→ Hand back (validate-chunk re-validates)
                         │
                         └─── Complex ───→ Ask for guidance
                                               │
                                               └─── Hand back (validate-chunk re-validates)

Remember

• **Fix the error, not the code** — minimal changes only
• **One thing at a time** — don't bundle fixes
• **Hand back after each fix** - validate-chunk re-runs validation; refine-chunk runs no commands
• **Know when to stop** — escalate complex issues
• **Always end output with `>>> HAND BACK TO validate-chunk:`.** This is the return signal. validate-chunk re-validates immediately upon seeing it.

Your goal: Get validation green