css-refactor-advisor

> **GUIDANCE SKILL — INSTRUCTIONS ONLY** > CSS/SCSS architecture analysis focuses on identifying redundancy, specificity conflicts, responsive design fragmentation, maintainability gaps, and performance bottlenecks in style codebases. > This skill provides patterns, conventions, and constraints. It contains no executable code — apply the guidance to your context, adapting specifics as needed per C2-B. ## CRITICAL: Guidance Principles The instructions below define the **REQUIRED APPROACH** — you MUST follow the prescribed patterns, conventions, and constraints. **Mandatory adherence:** - Follow all stated conventions and naming patterns - Respect all constraints and boundaries - Apply the recommended patterns to your implementation - Do NOT deviate from prescribed architectural decisions - Never modify any files; the analysis is strictly read-only - Every complex issue MUST include a before/after code snippet demonstrating the suggested refactor ## Correct Application Pattern 1. Read and absorb all guidance sections below 2. Map the prescribed patterns to your current context 3. Implement following the stated conventions — adapt specifics to fit, but preserve the intent 4. Validate against the C3 checklist at the end ## Argument Details | Arg | Type | Required | Default | Description | |-----|------|----------|---------|-------------| | target | string | Yes | — | Path to the style file or directory to analyze | ## Design Patterns & Conventions ### Architectural Pattern Multi-dimensional style audit: every analysis MUST examine the target styles through all five dimensions — Redundancy & Duplication, Specificity Issues, Responsive Design, Maintainability, and Performance. Each dimension is independently assessed, and findings are merged into a single severity-ranked report with concrete refactoring suggestions. ### Naming Conventions Findings are categorized using five standard labels that correspond to the analysis dimensions: | Category | Scope | |----------|-------| | Redundancy | Repeated style blocks, mergeable selectors, unused styles | | Specificity | Overly specific selectors, `!important` abuse, selector wars | | Responsive | Media query fragmentation, breakpoint inconsistencies, layout breakage | | Maintainability | Non-semantic class names, magic numbers, missing variables, BEM violations | | Performance | Expensive properties in animations, overly complex selectors, repaint/reflow risks | ### File / Module Organization The output is a single structured Markdown report composed of: 1. A **findings table** with columns: Location (file:line), Category, Explanation, Suggestion — sorted by impact (highest first) 2. **Before/after code snippets** for complex issues (inline after each applicable table row or in a dedicated section) 3. An **overall score** (1–10) with a prioritized list of top improvements ### Data Flow ``` Read target file(s) ({{target}} — single file or directory) → Parse and catalog all style rules → Scan for redundancy: identical blocks, mergeable selectors → Analyze specificity: selector depth, !important usage → Audit responsive design: breakpoint placement, media query nesting → Review maintainability: naming, variables, magic numbers → Check performance: animation properties, selector complexity → Merge findings, produce Markdown report (table + snippets + score) ``` ## Constraints & Boundaries ### Hard Constraints (non-negotiable) - **Read-only**: Never modify any files, styles, or configuration. The analysis is purely observational. - **Target required**: The `{{target}}` argument is mandatory — the analysis cannot proceed without a valid file or directory path. - **All five dimensions**: Every analysis MUST examine Redundancy, Specificity, Responsive Design, Maintainability, and Performance. If a dimension yields no findings, explicitly note that. - **Before/after for complex issues**: Any finding that involves a structural refactor (not a simple rename or value change) MUST include a before/after code snippet. ### Soft Guidelines (preferred but flexible) - Prefer concrete before/after code snippets over prose-only explanations for all findings, even simple ones. - When analyzing a directory, group findings by file to make the report easier to navigate. - For BEM-related findings, reference the specific BEM rule being violated (Block, Element, or Modifier). - Do not run build tools, linters, or dev servers — rely on static code analysis alone. - Prioritize specificity and redundancy issues over cosmetic naming suggestions when ranking severity. ## Implementation Guidance ### Step-by-step Approach 1. **Validate target**: Confirm `{{target}}` points to an existing file or directory. If not, report the error and halt. 2. **Read all style files**: If `{{target}}` is a file, read it directly. If a directory, glob for `*.css`, `*.scss`, `*.less` and read all matches. 3. **Parse and catalog**: For each file, extract all rule sets, noting selectors, properties, values, and line numbers. 4. **Dimension-by-dimension analysis**: - **Redundancy & Duplication**: Compare rule sets across files. Flag identical blocks, mergeable selectors with shared properties, and styles with zero usage (unreferenced in markup). - **Specificity Issues**: Calculate selector specificity scores. Flag selectors exceeding a depth of 4, any use of `!important`, and ID selectors in reusable component styles. - **Responsive Design**: Audit media query distribution — flag breakpoints scattered across files instead of being co-located, missing min/max constraints, and conflicting breakpoint values. - **Maintainability**: Check for semantic class naming (BEM or project convention), CSS custom property / SCSS variable usage vs. magic numbers, and consistent units. - **Performance**: Identify expensive properties in animations (e.g., `width`, `height`, `top`, `left` instead of `transform`), deeply nested selectors causing broad DOM matching, and excessive universal selector usage. 5. **Classify and rank**: Assign each finding to a category. Sort by impact: Redundancy/Specificity → Performance → Responsive → Maintainability. 6. **Draft before/after snippets**: For complex issues, write a concise before/after code block demonstrating the suggested refactor. 7. **Produce report**: Build the Markdown findings table, append before/after snippets, compute the overall score (1–10), and list the top priority improvements. ### Key Decisions | Decision | Rationale | Trade-offs | |----------|-----------|------------| | Target is mandatory | Style analysis without a target is meaningless; prevents accidental full-codebase scans | Less convenience for quick "review everything" requests | | Five analysis dimensions | Covers the full lifecycle of style technical debt | Some overlap between Maintainability and Redundancy (e.g., duplicate variables) | | Before/after required for complex issues | Concrete examples are more actionable than prose; CSS refactors are visual by nature | Increases report length; simple issues may feel under-documented | | Redundancy/Specificity ranked above Maintainability | These have the highest impact on runtime behavior and developer friction | Cosmetic issues may be deprioritized even when numerous | | No build or lint tools | Keeps analysis fast and self-contained; avoids toolchain dependencies | Cannot detect runtime-only issues like unused styles from dynamic class toggling | ## Usage Notes ### Input / Output **Input:** A required file path or directory path via `{{target}}`. When a directory is provided, all `.css`, `.scss`, and `.less` files within it (recursively) are analyzed. Single files of any supported extension are analyzed directly. **Output:** A Markdown report containing: 1. A **findings table** with columns: Location (file:line), Category, Explanation, Suggestion — sorted by impact. 2. **Before/after code snippets** for complex findings. 3. An **Overall Score** (1–10). 4. **Top Priority Improvements** — a ranked bullet list of the highest-impact action items. ### Feature Support | Feature | Input | Output | |---------|-------|--------| | Single file analysis | CSS/SCSS/Less file path | Targeted report for one file | | Directory analysis | Directory path | Multi-file aggregated report grouped by file | | Cross-file redundancy detection | Directory path | Merged findings across all style files | | Before/after snippets | Complex finding | Inline code block in report | ### Edge Cases - **Empty style file**: Report "No styles found" with score N/A — do not fabricate issues. - **No style files in directory**: If glob returns zero matches, report "No CSS/SCSS/Less files found in {{target}}" and halt. - **Mixed preprocessors**: If a directory contains both `.scss` and `.less` files, analyze each with its own syntax rules and note the mix in the report. - **Very large files**: If a file exceeds reasonable context size, analyze the first 2000 lines and note the truncation. - **Invalid target path**: If `{{target}}` does not exist or is outside the workspace, report the error and halt immediately. - **CSS-in-JS / styled-components**: These are outside the scope of this skill; note them as "skipped (CSS-in-JS)" and do not attempt to analyze. ### Self-Check Before C3 Before running the formal C3 verification, confirm: - All five dimensions have been examined (even if some yielded no findings). - Every table row has all four columns populated (Location, Category, Explanation, Suggestion). - Complex issues have accompanying before/after snippets. - The overall score and top priority improvements are present. - No files have been modified. ## Common Pitfalls > **Over-adaptation**: "Adapt specifics to fit" does not mean rewrite the core patterns. When in doubt, preserve the prescribed approach over local convenience — the patterns exist for a reason. > **Pattern drift**: As implementation progresses, it's easy to gradually deviate from conventions. Regularly re-read the Design Patterns section to catch drift early. > **Surface-level duplication scan**: Do not limit findings to "these two blocks are identical." Examine the cascade — a repeated block may be necessary due to specificity battles elsewhere, and the real fix may be restructuring the selector hierarchy. > **Ignoring the cascade**: CSS is not isolated per-file. When reviewing a component's styles, always consider inherited styles, global resets, and parent-level rules that affect the component. A selector that looks clean in isolation may be compensating for a problematic upstream rule. > **Vague suggestions**: "Use a variable" or "Refactor this" are not actionable. Every suggestion must be concrete — propose the exact variable name, the merge target selector, or the specific BEM restructuring. ## C3 Verification | Check Item | Constraint | Common Omission | Method | |------------|-----------|----------------|--------| | Pattern adherence | Prescribed patterns followed | Divergent implementation | Compare against Design Patterns section | | Naming conventions | Conventions applied consistently | Inconsistent naming | Grep / code review | | Hard constraints | All non-negotiable constraints met | Constraint violation | Manual checklist verification | | File organization | Modules/files structured as prescribed | Misplaced or missing files | Directory structure review | | All dimensions covered | Five analysis dimensions examined | Missing Performance or Responsive | Cross-reference report against Analysis Dimensions | | Findings table complete | Every row has Location + Category + Explanation + Suggestion | Missing Location or Category | Table cell inspection | | Before/after for complex issues | Complex findings include code snippets | Complex issue with prose-only fix | Scan for complex findings; verify snippet presence | | Overall score present | Score (1–10) + prioritized improvements | Score without ranked action items | Verify both elements in output | | Read-only enforced | No files modified during analysis | Accidental edit or write | Confirm no write/edit tools were invoked |