/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

**Always synchronous:**

• **NEVER use `run_in_background: true` for test, typecheck, lint, or build commands.** Run everything synchronously so results are confirmed before proceeding.
• Background runs become orphaned and spam the conversation after the story is done.

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. Re-validate

After fix:

• Run same validation that failed
• Confirm error is resolved
• Check for new errors introduced

**Output after re-validation:**

When re-validation passes, report:

## Refinement Applied

[Fix details per output template]

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

When re-validation reveals new errors, report them and loop (attempt another fix if REFINE_COUNT allows).

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 ───→ Re-validate
                         │
                         └─── Complex ───→ Ask for guidance
                                               │
                                               └─── Re-validate

Remember

• **Fix the error, not the code** — minimal changes only
• **One thing at a time** — don't bundle fixes
• **Verify after each fix** — re-run validation
• **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 with surgical precision.

Orchestrator Integration

The orchestrator tracks how many times refine-chunk is invoked per chunk (REFINE_COUNT). If invoked 2+ times for the same chu