Delegate menial lookups to Haiku (cost control)
During this skill, push pure read-only lookups DOWN to a cheap subagent instead of running them on the current model. This covers: multi-file grep/glob, "where is X defined / what calls Y", mapping a directory, reading many files to locate something, or fetching a URL for reference.
Use the Agent tool with the caveman:cavecrew-investigator subagent (Haiku,
returns a compressed file:line answer). If that subagent is unavailable, spawn a
general agent with model: haiku. Keep all reasoning, decisions, and edits on
the current model. Delegate only the menial searching.
Improve Component
Analyze specific files or components for modularity, reusability, and hygiene. Propose focused refactors that make components easier to test, reuse, and maintain.
Contract
Format: task file — see contracts/task-contract.md (schema_version: "1")
Role: producer
Step-0 — validate output before returning:
bash ~/.dotfiles/claude-code-shared/scripts/shared/validate-schema.sh \
--instance ~/.dotfiles/claude-code-shared/contracts/task-schema.json \
<output-path>
On non-zero exit: STOP. Report stderr to the user. Do not write the file.
This skill operates on individual files or small clusters of related files.
Principles
Apply these in order of impact. Not every principle applies to every file. Flag only what matters.
1. Business Logic Separation
Business logic and presentation must live in separate layers. A component that fetches data, transforms it, manages state, AND renders UI is doing too much.
Pattern: Extract business logic into custom hooks or plain functions. The component becomes a thin rendering layer that receives data and callbacks.
Test: Can you test the business logic without rendering anything? Can you test the presentation with stub data and no real API calls? If no to either, the layers are coupled.
Signals of violation:
useEffectwith fetch/mutation logic inside a component that also renders UI- State transformations (filtering, sorting, aggregation) mixed with JSX
- Event handlers that contain business rules, not just delegation
- Components that import API clients or service modules directly
2. Design System Adherence
Presentation layers should use design system components and tokens wherever possible. Every one-off styled element is a drift risk.
Before creating any UI element, check:
- Does a design system component already handle this? (
/src/design-system, shadcn, or whatever the project uses) - Does a shared UI component already exist? (
/src/shared-uior equivalent) - Are spacing values using theme tokens, not raw px/rem?
- Are colors, typography, and shadows using theme values?
Signals of violation:
- Inline styles with hardcoded values
- Styled-components or CSS that duplicate design system primitives
- Custom button/input/modal/card when a DS version exists
- Raw HTML elements (
<div>,<span>) used for layout instead of DS layout primitives - Magic numbers for spacing, font sizes, or breakpoints
3. Single Responsibility
Each component does one thing. If describing it requires "and", it should split.
Test: Describe the component in one sentence. If you need a conjunction, identify the two responsibilities and evaluate whether splitting improves clarity.
Signals of violation:
- Component name includes "And" or describes two behaviors
- Multiple unrelated
useEffecthooks - Render function has distinct visual sections with independent data needs
4. Props Interface Minimality
Fewer props = more reusable. Pass only what the component needs.
Signals of violation:
- Receiving a large object but only using 2-3 fields
- Boolean props that toggle between two entirely different render paths (should be two components)
- More than ~6 props (consider grouping or splitting)
- Props passed only to forward to a child (prop drilling)
5. Composition Over Configuration
Components with many boolean/enum props that toggle behavior should split into composable pieces.
Prefer: <Card><CardHeader /><CardBody /></Card>
Over: <Card showHeader showFooter variant="sidebar" />
Signals of violation:
- Multiple boolean props that control which sections render
variantortypeprop with a switch statement in the render- Conditional rendering blocks that are each 20+ lines
6. Custom Hook Extraction
When a component has complex state logic or effects, extract to a named hook.
Benefits: Hook is independently testable. Component becomes declarative. Logic is reusable across components.
When to extract:
- 3+
useStatecalls that interact with each other useEffect+useStatepatterns (loading/error/data)- State machine logic (multi-step forms, wizards)
- Debounce/throttle/polling patterns
When NOT to extract: Single useState for UI toggle. Simple form with 2 fields. Extraction adds a file but no clarity.
7. Naming Clarity
Names describe what, not how. Names describe what the thing IS, not where it's used.
Components: Describe what they render. InvoiceLineItem not TableRow3. UserAvatar not SmallImage.
Hooks: Describe what state they manage. useInvoiceForm not useFormStuff.
Variables: isLoading not flag. selectedUserId not id. handleSubmit not doIt.
Files: Match the primary export. InvoiceLineItem.tsx not row.tsx.
8. Colocation
Things used by one component live next to it. Things shared across components live at the nearest common ancestor.
Signals of violation:
- Types defined in a central
types/folder but used by one component - Helper functions in
utils/used by one file - Constants in a global file but relevant to one feature
9. Test Coverage Existence
Check whether a colocated test file exists for the target component.
Check for: ComponentName.test.tsx, ComponentName.spec.tsx, or a __tests__/ directory containing a matching test file.
If no test file exists: Flag it as a structural finding. A component without tests is a refactoring hazard.
If a test file exists: Glance at it. Flag if it only tests trivial rendering ("renders without crashing") and lacks coverage of meaningful behavior, props, or edge cases.
Scope: This principle surfaces the gap. Tests are written in the execution step (step 7).
10. File Size as a Signal
Not a hard limit, but files over ~200 lines usually contain extractable pieces. The question is always: does splitting improve clarity, or just scatter code?
Split when: Distinct responsibilities exist within the file. Independent testability would improve. A section is reusable elsewhere. Don't split when: The pieces only make sense together. Splitting just creates a file-hopping burden. The file is long but linear and readable.
11. TypeScript Hygiene
Type safety is structural, not cosmetic. Loose types mask bugs and break refactor confidence.
Signals of violation:
anycasts that are not explicitly justified- Missing generics where type parameters would narrow behavior
- Overly broad union types (
string | object | undefined) where a discriminated union would work - Props typed as
objectorRecord<string, any>instead of a named interface - Return types omitted on exported functions and hooks
- Type assertions (
as Foo) instead of narrowing
12. Accessibility
React components must be usable by keyboard and screen reader without extra work.
Check:
- Interactive elements use semantic HTML (
<button>,<a>,<input>) not<div onClick> - Images have
alttext (empty stringalt=""for decorative images is correct) - Form inputs have associated
<label>elements oraria-label - Modals and dialogs trap focus and restore it on close
- Dynamic content changes are announced via
aria-livewhere appropriate - Color is not the only means of conveying information
Signals of violation:
onClickon a<div>or<span>with noroleortabIndex<img>withoutalt<input>without a label association- Focus lost after a modal closes
Process
1. Receive target
User provides one or more file paths. If no paths given, ask: "Which files or components should I look at?"
If the user points at a directory, list the files in it and ask which to focus on. Don't analyze an entire directory unprompted.
2. Read and understand
Issue all of the following in the same turn (parallel — none depend on each other):
- Read the target file(s) fully
- Read direct imports (one level deep) to understand dependencies
- Read sibling files (
ComponentName.css,ComponentName.types.ts,ComponentName.utils.ts) - Read the test file if one exists
- Spawn
context-loader(subagent_type: context-loader, repo root)
Wait for all reads and the context-loader result before step 3. Use vocabulary terms throughout your analysis for domain concepts. From adrs[], deep-read full text only for those whose path is relevant to this component's area — they explain intentional trade-offs that look like violations. Do not glob docs/adr/ directly. From sources[], deep-read any typed sources relevant to this component (e.g. design-system, brand-colors, brand-typography).
Understand what the component does before evaluating how it's structured. An ADR may explain why a principle appears violated.
3. Identify the design system
Use sources[] from the context-loader payload first (type design-system). If a pointer was returned, Read the file it points to for available components. If no design-system source was returned, locate the design system manually by checking these locations in order:
/src/design-system/or/src/ds/- shadcn component directory (often
/src/components/ui/) - A component library in
package.json(e.g.@radix-ui,@chakra-ui,@mui) /src/shared-ui/or/src/common/
If found via either path, scan available components so you can recommend specific replacements. If not found, skip design system checks and note that no DS was detected.
4. Analyze against principles
Evaluate each principle. For each violation found, note:
- Which principle is violated
- The specific code location (file:line)
- Why it matters (impact on testability, reusability, or maintainability)
- What the fix looks like (concrete, not vague)
Skip principles that don't apply. Don't manufacture findings.
5. Present findings
Group findings by severity:
Structural (affects testability or reusability):
- Business logic mixed with presentation
- Missing design system usage where DS components exist
- Components doing multiple unrelated things
- TypeScript
anycasts or missing generics on public interfaces - Accessibility violations on interactive elements
Hygiene (affects readability and maintainability):
- Naming issues
- Colocation violations
- File size concerns
- Prop interface issues
- Missing or trivial test coverage
Format each finding as:
<file>:L<line> - <principle>: <problem>. <fix>.
End with a prioritized recommendation: "Start with X because it unlocks Y."
Clean bill of health path: If analysis finds no structural or hygiene violations worth flagging, check for test coverage before ending.
- Look for a colocated test file (
ComponentName.test.tsx,ComponentName.spec.tsx, or__tests__/ComponentName.*). - If no test file exists or the file only has trivial "renders without crashing" coverage: use
AskUserQuestionto ask: "Component looks good. No meaningful test coverage found. Want me to generate a task to backfill tests via/build-code?" If yes, go to step 7 with one task: backfill characterization tests. If no, end. - If adequate test coverage exists: note it and end.
6. Discuss and refine
Don't start refactoring immediately. Ask the user which findings they want to act on. Some may be intentional trade-offs. An ADR you found may already justify a finding.
Present findings as a numbered list and ask: "Which of these do you want to act on?"
7. Write tasks file
After the user approves changes, write a tasks file before touching any code.
Step 7a: Branching. gxcheck pre-flight: Before asking the user, run ~/.dotfiles/.scripts/gxcheck and surface its output as a brief status block (e.g. Branch check: OK: branch looks clean). This is advisory only — the skill continues regardless of the output. Then run git branch --show-current and ask:
Branching strategy:
1. Single branch for all tasks (you provide the name) — best for a focused refactor or if you want to stay on your current branch
2. Per-task branches (auto-generated) — best for independent improvements reviewed separately
Which do you prefer?
If single: ask "Branch name?" and suggest refactor/<component-slug>-improvements as a default. If the user is already on a feature or fix branch, note that they can stay on it. If per-task: derive branch names per branching-strategy.md.
Wait for user response before continuing.
See ~/.dotfiles/claude-code-shared/resources/branching-strategy.md for branch naming rules, derivation format, and JSON recording format.
Step 7b: Write the file. Run ~/.dotfiles/claude-code-shared/scripts/scaffolding/next-task-id.sh docs/tasks/ and ~/.dotfiles/claude-code-shared/scripts/scaffolding/task-filename.sh improve-<component-slug>.
Write one task per approved finding (or group tightly coupled findings into one task with compound acceptance criteria). Each task must be self-contained. Embed the specific file path, line numbers, principle violated, and exact fix approach in the description.
Follow the canonical schema in ~/.dotfiles/claude-code-shared/contracts/task-schema.json. Do not define the JSON structure inline.
Key field values for improve-component tasks:
schema_version:"2"producer:"improve-component"source:{"type": "session", "ref": null}(no upstream document for component improvement runs)
HITL tasks (rare — e.g. "rotate the API key before refactoring the credential helper") must be hands-only: a keyboard action the AI cannot perform. Never emit a decision-review HITL task.
branching: use the strategy and branch from Step 7a (see branching-strategy.md for JSON format)description:"Principle violated: <name>. Location: <file:line>. Problem: <what is wrong and why it matters>. Fix: <concrete steps>."acceptance_criteria[0]: always a test criterion ("Characterization test exists at <path> covering the behavior being changed before any refactor"for refactors, or"Failing test exists at <path>"for new behavior)
After writing the file, output:
Tasks written: docs/tasks/<filename>
Tasks: <T-XXXX list>
8. Hand off to build-code
Tell the user:
Next steps:
Then run:
python3 ~/.dotfiles/claude-code-shared/scripts/shared/print-skill-next-steps.py improve-component
Append that output under the Next steps header. Do not hardcode skill names. Do not invoke /tdd directly. Do not make any code changes. All execution happens in /dispatch-tasks.
Read and execute ~/.dotfiles/claude-code-shared/resources/learning-capture.md.
This skill's slug is improve-component.
/dispatch-tasks— tasks file is written and ready to execute