home / skills / busirocket / agents-skills / busirocket-refactor-workflow

busirocket-refactor-workflow skill

safe

This skill guides strict refactoring of TS/React code, ensuring one export per file and mandatory post-refactor checks to elevate quality.

npx playbooks add skill busirocket/agents-skills --skill busirocket-refactor-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (11)

SKILL.md

2.5 KB

---
name: busirocket-refactor-workflow
description:
  Strict refactoring workflow for TypeScript/React codebases. Use when
  refactoring files with multiple exports, splitting components/hooks/utils,
  moving inline types to types/, and enforcing post-refactor quality gates.
metadata:
  author: cristiandeluxe
  version: "1.0.0"
---

# Refactor Workflow

Strict, step-by-step refactoring guidance for maintaining code quality.

## When to Use

Use this skill when:

- Refactoring files with multiple exports (use `@file` workflow)
- Splitting components/hooks/utils into smaller files
- Moving inline types to `types/`
- Enforcing post-refactor quality checks

## Non-Negotiables (MUST)

- After any refactor: run the project's standard checks (e.g. `yarn check:all`)
  as a mandatory quality gate.
- If a file has multiple responsibilities, split immediately.
- If a hook/component contains helpers, extract them.
- If a file declares types inline, move them to `types/`.
- Never use index/barrel files; import from concrete modules only.

## @file Refactor Workflow

When referencing `@file` for a one-shot refactor:

- Exactly one exported symbol per file.
- No inline `interface`/`type` declarations in non-type files.
- No helper functions inside components/hooks.

## Rules

### @file Refactor Workflow

- `refactor-file-workflow` - @file refactor workflow (strict constraints)
- `refactor-mandatory-checks` - Mandatory checks after refactor

### Refactoring TypeScript/React

- `refactor-goals` - Goals for refactoring (many small files, one export per
  file)
- `refactor-decision-rules` - Decision rules for when to split files
- `refactor-never-index-files` - Never use index files
- `refactor-post-refactor-checks` - Post-refactor checks (MANDATORY)

### Post-Refactor Checks

- `refactor-golden-path` - Golden path for post-refactor checks
- `refactor-file-size-guidelines` - File size targets and max lines
- `refactor-if-something-fails` - What to do if checks fail
- `refactor-when-to-split` - Fast heuristics for when to split files

## Related Skills

- `busirocket-core-conventions` - File structure and boundaries
- `busirocket-typescript-standards` - TypeScript standards to enforce
- `busirocket-react` - Component/hook patterns

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/refactor-file-workflow.md
rules/refactor-decision-rules.md
rules/refactor-post-refactor-checks.md
```

Each rule file contains:

- Brief explanation of why it matters
- Code examples (correct and incorrect patterns)
- Additional context and best practices

Overview

This skill provides a strict, repeatable refactoring workflow for TypeScript and React codebases. It enforces one-export-per-file, moves inline types to a dedicated types/ folder, and requires mandatory post-refactor quality gates. Use it to keep large codebases modular, predictable, and easy to review.

How this skill works

The skill defines concrete rules and a one-shot @file refactor workflow: split files so each exports exactly one symbol, extract helpers from components and hooks, and relocate inline interfaces/types into types/. After changes, it runs the project’s standard checks as a blocking gate and offers guidance on what to do when checks fail. Rule documents include examples and decision heuristics for splitting files and sizing targets.

When to use it

Refactoring files that have multiple exports into single-responsibility modules
Splitting large components, hooks, or utility files into smaller files
Moving inline type/interface declarations into a centralized types/ directory
Enforcing mandatory post-refactor checks and CI-quality gates
Applying consistent import practices (no index/barrel imports)

Best practices

Always run the project’s standard checks after any refactor (e.g., yarn check:all) and treat failures as blocking
Limit each file to a single exported symbol — one component, hook, or util per file
Extract helper functions from components and hooks into their own modules when they have separate responsibilities
Move inline types and interfaces to a types/ folder and import them explicitly from concrete modules
Avoid index/barrel files; import directly from the concrete module path to keep boundaries explicit

Example use cases

Refactor a utilities file with several exported functions into separate files under utils/ with one export each
Split a large React component into a presentational component and several small child components and extract helpers into hooks or utils
Move inline type/interface declarations from a component file into types/ and update imports across the codebase
Run the post-refactor golden path: refactor, run checks, fix lint/type/test failures, open a focused PR

FAQ

What if post-refactor checks fail and I need more time?

Treat checks as blocking. Create a focused follow-up branch or PR that fixes the failures. Document the issue and include testing steps; don’t merge until checks pass.

Can I use index/barrel files for convenience?

No. The workflow forbids index/barrels to preserve explicit module boundaries and reduce accidental coupling.