@bovinphang/frontend-craft 2.8.0 → 2.9.0

package/skills/fec-refactoring/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: fec-refactoring
+description: Use when restructuring existing frontend code while preserving observable behavior, including responsibility extraction, module movement, conditional simplification, API cleanup, or data organization. Do not use for new feature behavior, behavior-changing bug fixes, dependency or framework migrations, or proven dead-code cleanup.
+---
+
+# Skill: Behavior-Preserving Refactoring
+
+## Purpose
+
+Restructure live frontend code in small, evidence-backed steps while preserving the behavior users, callers, tests, routes, and integrations can observe.
+
+## Core Contract
+
+Every execution follows these rules:
+
+1. **Behavior Preservation** — pure refactoring intentionally changes structure, not observable behavior.
+2. **Green Baseline First** — record available verification before editing.
+3. **One Refactoring at a Time** — one primary structural intent per step.
+4. **Verify Every Step** — run the narrowest meaningful check immediately after each step.
+5. **Revert Before Repairing** — if a new regression appears, revert that step before widening the edit.
+6. **Separate Refactoring from Feature Work** — behavior changes belong in a different workflow.
+7. **Smallest Safe Refactoring First** — prefer the narrowest transformation that fits the evidence.
+8. **Stay Within the Diff Budget** — stop when actual scope materially exceeds the planned scope.
+
+Pure refactoring uses **GREEN → REFACTOR → GREEN**. Do not manufacture a failing behavioral test merely to make a structural change look like feature TDD.
+
+## Procedure
+
+1. **Classify the request.** Confirm that the intended result is structural and behavior-preserving.
+2. **Discover context.** Read project configuration, affected modules, public exports, routes, state boundaries, tests, and current diff.
+3. **Record observable contracts.** Capture inputs, outputs, errors, side effects, UI states, events, network calls, state transitions, routes, and public APIs that matter.
+4. **Establish the baseline.** Run existing narrow checks first; record pre-existing failures rather than attributing them to later edits.
+5. **Diagnose structural evidence.** Identify the concrete smell or responsibility problem and check likely false positives.
+6. **Build the safety net.** Reuse relevant tests; add characterization coverage only when needed to preserve existing behavior.
+7. **Plan ordered micro-refactorings.** For each step record technique, rationale, prerequisites, risk, Diff Budget, verification, and rollback boundary.
+8. **Apply exactly one primary transformation.** Avoid opportunistic cleanup, formatting churn, or unrelated redesign.
+9. **Verify immediately.** Compare actual scope with the Diff Budget and run targeted checks.
+10. **Handle regression.** Revert the current step, confirm the prior baseline, shrink or reorder the transformation, then retry only with evidence.
+11. **Run broad final validation.** Escalate from targeted checks to typecheck, tests, build, E2E, accessibility, or specialty checks when relevant.
+12. **Report proof strength.** Use PASS, PARTIAL, or NOT PROVEN and state remaining risk.
+
+## Risk Classification
+
+| Risk | Typical scope | Default action |
+| --- | --- | --- |
+| `SAFE` | Local/private code, stable contracts, easy rollback | Execute with step-level verification |
+| `CAUTION` | Cross-module movement, shared state, imports, hooks/composables, lifecycle | Execute only with adequate safety evidence |
+| `DANGER` | Public API, routes, persistence, network contracts, auth, SSR/hydration, broad state or inheritance redesign | Plan and stop for explicit approval unless already authorized |
+
+Risk is contextual. A technique name alone never proves that a change is safe.
+
+## Diff Budget
+
+Before each executable step record:
+
+```text
+Expected files: N
+Expected functions/components: N
+Expected public API changes: 0
+Expected behavior changes: 0
+```
+
+If the actual diff materially exceeds that budget, stop and reassess instead of silently expanding into redesign.
+
+## References
+
+- Load [principles.md](references/principles.md) for the safety rules, evidence model, and risk language.
+- Load [workflow.md](references/workflow.md) for the state machine, baseline handling, rollback, and reporting contract.
+- Load [when-to-refactor.md](references/when-to-refactor.md) when deciding whether restructuring is timely or should be deferred.
+- Load [refactoring-vs-feature-change.md](references/refactoring-vs-feature-change.md) when ownership overlaps feature work, debugging, cleanup, migration, or review.
+
+## Constraints
+
+- Do not alter tests merely to accept behavior changed by the refactoring.
+- Do not label auth, permission, routing, persistence, protocol, or public package changes `SAFE` without specific evidence.
+- Do not stack additional structural edits after a newly introduced failure.
+- Do not install a new test framework automatically when the project has none.
+- Do not treat line count, complexity metrics, comments, a switch, or chaining as sufficient proof of a code smell.
+- Do not perform remote Git writes by default.
+
+## Expected Output
+
+A small-step refactoring plan or implementation with explicit evidence, risk, Diff Budget, per-step verification, rollback history when applicable, and a final PASS/PARTIAL/NOT PROVEN behavior-preservation verdict.

package/skills/fec-refactoring/references/principles.md

@@ -0,0 +1,60 @@
+# Refactoring Principles
+
+## Definition
+
+Refactoring changes the internal organization of existing code without intentionally changing its observable behavior. The purpose is to make future change safer and easier, not to smuggle new behavior into a structural patch.
+
+## Eight Hard Rules
+
+1. **Behavior Preservation:** define the relevant observable contract before substantial edits.
+2. **Green Baseline First:** distinguish pre-existing failures from regressions introduced by the current step.
+3. **One Refactoring at a Time:** keep each step attributable to one structural intent.
+4. **Verify Every Step:** use feedback at the smallest useful scope before continuing.
+5. **Revert Before Repairing:** a new regression invalidates the current step; restore the previous state before redesigning it.
+6. **Separate Feature Work:** new outcomes, changed rules, or changed error behavior are not pure refactoring.
+7. **Smallest Safe Refactoring First:** prefer a reversible local change over a speculative redesign.
+8. **Stay Within the Diff Budget:** scope growth is a stop signal, not permission to keep expanding.
+
+## Observable Behavior
+
+Depending on the code, preservation can include:
+
+- return values, thrown errors, and error mapping;
+- side effects and their ordering when order is semantically significant;
+- requests, payloads, retries, cancellation, and authentication behavior;
+- state transitions, persistence, cache identity, and memoization-sensitive object identity;
+- rendered DOM, loading/error/empty states, focus, keyboard behavior, and emitted events;
+- props, emits, slots, hook/composable contracts, package exports, routes, and URLs.
+
+## Evidence Model
+
+Use concrete evidence before choosing a technique:
+
+- call sites and dependency direction;
+- ownership of the data being read or mutated;
+- change history or repeated edit locations when available;
+- tests and documented public contracts;
+- runtime registration points, dynamic imports, route tables, i18n keys, Storybook stories, and generated templates;
+- framework lifecycle semantics and state identity.
+
+Metrics may indicate where to look, but they do not independently prove the diagnosis.
+
+## Risk Model
+
+### SAFE
+
+Local/private scope, no public contract, no subtle lifecycle or persistence semantics, strong rollback path, and relevant verification available.
+
+### CAUTION
+
+Cross-file or cross-component restructuring, shared helpers, state ownership changes, lifecycle-sensitive code, dynamic references, or incomplete behavioral coverage.
+
+### DANGER
+
+Public APIs, routes, storage schemas, backend contracts, authentication or permissions, SSR/hydration, critical calculations, broad inheritance replacement, or architecture-wide state movement.
+
+Do not assign permanent risk to a catalog technique. The same rename can be SAFE for a local variable and DANGER for a serialized field.
+
+## Characterization Before Risky Change
+
+When important current behavior is not directly tested, add characterization coverage that describes what the code already does. Such a test can start green; its purpose is to lock existing behavior, not to invent a new requirement.

package/skills/fec-refactoring/references/refactoring-vs-feature-change.md

@@ -0,0 +1,27 @@
+# Refactoring Boundaries
+
+## Pure Refactoring
+
+Use the behavior-preserving lane when the requested outcome is structural: clearer responsibilities, smaller functions, better names, safer encapsulation, moved behavior, simplified conditionals, cleaner API shape, or improved data organization without an intentional change to what callers or users observe.
+
+Verification model: **GREEN -> REFACTOR -> GREEN**.
+
+## Feature or Behavior-Changing Defect Work
+
+A request is not pure refactoring when it adds a capability, changes a business rule, changes accepted input, changes visible output, changes an error outcome, or intentionally changes side effects. Establish the new desired behavior with a failing behavioral test before implementation.
+
+## Debugging
+
+When the failure cause is unknown, diagnose root cause before choosing structural changes. A refactoring may become part of a later fix, but it is not a substitute for evidence about the defect.
+
+## Dead-Code Cleanup
+
+Proven unused code, stale exports, unused dependencies, obsolete routes, and similar removal work require specialized reference discovery because dynamic imports, configuration, templates, routes, Storybook, CSS, and generated keys can create false positives. Keep cleanup separate from broad restructuring of live code.
+
+## Migration
+
+Framework, dependency, router, build-system, state-library, or architecture migrations intentionally alter compatibility boundaries and should be planned as migrations even when they also improve design.
+
+## General Review
+
+A merge-readiness review may identify structural findings, but review remains report-first. Diagnosis or a refactoring plan should be an explicit follow-up rather than silent source rewriting during review.

package/skills/fec-refactoring/references/when-to-refactor.md

@@ -0,0 +1,31 @@
+# When to Refactor
+
+## Refactor Now
+
+Refactor when a structural problem directly increases the cost or risk of the work currently in front of you and the intended behavior can be kept stable. Strong situations include:
+
+- a change is difficult because one responsibility is tangled with unrelated work;
+- the same concept must be edited in several places;
+- a public-looking API is difficult to use safely and a compatibility path exists;
+- duplicated decisions are already drifting;
+- state or data ownership is obscuring reliable reasoning;
+- tests are hard to target because responsibilities are fused.
+
+## Record and Defer
+
+Defer when the smell is real but unrelated to the current goal, the safety net is insufficient for a risky transformation, or the required compatibility work is larger than the immediate value. Record evidence and a candidate sequence instead of starting an opportunistic redesign.
+
+## Stop Refactoring
+
+Stop when:
+
+- the structural objective has been met;
+- the next step changes observable behavior;
+- the next step crosses a public contract without an explicit compatibility plan;
+- the Diff Budget is expanding materially;
+- verification can no longer distinguish a regression from the baseline;
+- the remaining motivation is aesthetic preference rather than change cost or correctness risk.
+
+## Practical Heuristic
+
+A useful refactoring makes the next meaningful change easier to understand, localize, verify, or reverse. If it does not improve one of those properties, require stronger evidence before continuing.

package/skills/fec-refactoring/references/workflow.md

@@ -0,0 +1,90 @@
+# Refactoring Workflow
+
+## State Machine
+
+```text
+CLASSIFY REQUEST
+  -> DISCOVER CONTEXT
+  -> ESTABLISH BASELINE
+  -> DIAGNOSE STRUCTURAL EVIDENCE
+  -> ESTABLISH SAFETY
+  -> BUILD ORDERED PLAN
+  -> RISK CHECK
+  -> EXECUTE ONE STEP
+  -> VERIFY STEP
+       PASS -> inspect diff -> next step
+       FAIL -> revert current step -> confirm baseline -> shrink/replan
+  -> FINAL VALIDATION
+  -> REPORT
+```
+
+## Context Discovery
+
+Read only what is needed to establish facts:
+
+- `package.json`, workspace manifests, TypeScript and lint configuration;
+- test configuration and scripts;
+- affected modules, callers, imports, barrel exports, routes, and registration points;
+- state/store ownership and persistence boundaries;
+- framework conventions, lifecycle-sensitive code, async effects, and current Git diff.
+
+## Baseline Handling
+
+If the baseline is green, any newly failing relevant check after a step is presumptive evidence that the step regressed behavior or structure.
+
+If the baseline is already red:
+
+1. record exact failing commands and symptoms;
+2. do not claim later failures are caused by refactoring without comparison evidence;
+3. avoid risky restructuring unless the preserved contract remains credible;
+4. separate unexplained failure diagnosis from structural change.
+
+## Plan Step Contract
+
+Each executable step records:
+
+```text
+Target:
+Technique:
+Intent:
+Prerequisites:
+Risk: SAFE | CAUTION | DANGER
+Expected files:
+Expected functions/components:
+Expected public API changes: 0
+Expected behavior changes: 0
+Verification:
+Rollback boundary:
+```
+
+Order prerequisites before larger moves. For example, expose a stable query before extracting logic that depends on it, or isolate a conditional before replacing its dispatch mechanism.
+
+## Step Failure Protocol
+
+When a previously green check becomes red:
+
+1. stop;
+2. revert only the current structural step;
+3. rerun the affected check to confirm restoration;
+4. identify whether the failed assumption was behavior, identity, lifecycle, ordering, typing, or dependency related;
+5. shrink the step or add a safer prerequisite;
+6. retry only after the plan is again evidence-backed.
+
+Do not spread fixes across unrelated modules merely to make the suite green.
+
+## Final Validation
+
+Use a narrow-to-broad ladder:
+
+1. nearest syntax/type/static check;
+2. targeted unit or component tests;
+3. affected package or integration tests;
+4. lint and full typecheck;
+5. broader test suite;
+6. build, SSR, E2E, visual, accessibility, performance, or specialty checks when affected.
+
+## Proof Verdict
+
+- **PASS:** the relevant observable contract is adequately covered and required checks pass.
+- **PARTIAL:** executed checks pass, but important behavior remains incompletely covered.
+- **NOT PROVEN:** missing dependencies, environment limits, baseline failures, or insufficient safety evidence prevent a credible preservation claim.

package/skills/fec-refactoring-api/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: fec-refactoring-api
+description: Use when behavior-preserving frontend refactoring focuses on function API shape, flags, dependencies, mutability, construction, or command/function trade-offs, and the selected technique needs family-specific mechanics, risks, and JavaScript/TypeScript/React/Vue adaptation.
+---
+
+# API Refactorings
+
+## Overview
+Use this family after evidence identifies a fitting structural transformation. Apply one primary technique at a time and verify immediately.
+
+## Procedure
+1. Confirm the selected technique and its preconditions in [API Refactorings](references/api-refactorings.md).
+2. Record affected behavior and a diff budget.
+3. Apply only the selected technique's smallest viable step.
+4. Verify the step before composing another transformation.
+5. Stop and reassess when public contracts, lifecycle, state identity, or actual scope exceed expectations.
+
+## Quick Reference
+The family reference contains 10 canonical techniques with intent, signals, avoid conditions, mechanics, preservation checkpoints, smell links, composition hints, JavaScript/TypeScript notes, React/Vue notes, adaptation guidance, and original frontend examples.
+
+## Common Mistakes
+- Choosing a technique by name without checking its preconditions.
+- Combining several structural intentions in one diff.
+- Assuming a classical class-based form is mandatory in modern frontend code.
+- Treating passing tests as proof when the relevant behavior is not covered.