pm7y-css-review

What this skill does

# CSS/SCSS Review Skill

Reviews CSS/SCSS changes for unnecessary complexity and missed reuse opportunities. Produces analysis findings that are passed to `pm7y-ralph-planner` for TASKS.md generation.

---

## Overview

This skill analyzes CSS/SCSS files for three categories of issues:

- **Over-specificity** - Complex selectors that could be simpler
- **Missing reuse** - New styles that duplicate existing utilities
- **Over-engineered abstractions** - Unnecessary mixins/variables/extends

**Output:** Analysis findings passed to `pm7y-ralph-planner`, which generates a `TASKS.md` file with validation requirements and learnings tracking for autonomous execution via `pm7y-ralph-loop`.

**When to use:**

- Before committing CSS/SCSS changes
- During PR review of style changes
- Auditing existing stylesheets for cleanup
- After rapid UI development to assess CSS debt

---

## Usage

```
/pm7y-css-review                      # Review all CSS/SCSS changes in branch
/pm7y-css-review @path/to/file.scss   # Review specific file only
```

---

## Review Process

### Step 1: Determine Scope

Parse arguments to determine which files to review:

**If @file argument provided:**
- Extract the file path after the @ symbol
- Verify the file exists and is CSS/SCSS
- Review only that file

**If no arguments (default):**
- Run `git diff main...HEAD --name-only` to find files changed in branch
- Also check `git diff --name-only` for staged/unstaged changes
- Filter to only `.css` and `.scss` files
- If no CSS/SCSS files changed, report "No CSS/SCSS changes found" and stop

### Step 2: Build Style Inventory

Scan the project to understand existing styles:

**Find all style files:**
```bash
# Find all CSS and SCSS files in project (exclude node_modules, dist, build)
find . -type f \( -name "*.css" -o -name "*.scss" \) \
  -not -path "*/node_modules/*" \
  -not -path "*/dist/*" \
  -not -path "*/build/*" \
  -not -path "*/.next/*"
```

**Extract existing patterns:**

For each style file, identify and record:
- **CSS classes** - All `.class-name` selectors
- **SCSS variables** - All `$variable-name` definitions
- **SCSS mixins** - All `@mixin mixin-name` definitions
- **Common property-value pairs** - Frequently used declarations

Store this inventory mentally for comparison during analysis.

### Step 3: Detect Frameworks

Check for CSS frameworks to understand available utilities:

**Tailwind CSS:**
- Check for `tailwind.config.js` or `tailwind.config.ts`
- Look for `@tailwind` directives in CSS files
- If found, note common utilities: flex, grid, spacing (p-*, m-*), colors, etc.

**Bootstrap:**
- Check for Bootstrap in `package.json` dependencies
- Look for Bootstrap imports in SCSS files
- If found, note utility classes: d-flex, justify-content-*, text-*, etc.

**Custom utility systems:**
- Look for files named `utilities.css`, `helpers.scss`, `_utils.scss`
- Identify utility class naming patterns

### Step 4: Analyze Changed Files

For each file in scope, read the content and check for issues:

#### Over-specificity Detection

| Issue | Pattern | Severity |
|-------|---------|----------|
| Deep nesting | Selectors with > 3 levels (e.g., `.a .b .c .d`) | Medium |
| ID selectors | `#id` in selectors | Medium |
| `!important` | Any `!important` declaration | Medium |
| Qualified selectors | Element + class (e.g., `div.button`) | Low |
| Over-qualified | Multiple classes chained (e.g., `.btn.btn-primary.btn-large`) | Low |

#### Missing Reuse Detection

| Issue | Pattern | Severity |
|-------|---------|----------|
| Duplicate utility | Declaration matches existing utility class | High |
| Framework duplicate | Declaration available as framework utility | High |
| Repeated values | Magic numbers used instead of variables | Medium |
| Similar blocks | Near-identical declaration blocks elsewhere | Medium |

#### Over-engineered Abstraction Detection

| Issue | Pattern | Severity |
|-------|---------|----------|
| Single-use mixin | `@mixin` with only one `@include` | Medium |
| Single-use variable | `$variable` used only once (except colors) | Medium |
| `@extend` usage | Any use of `@extend` | Low |
| Deep SCSS nesting | > 3 levels of SCSS nesting | Low |

#### Existing Pattern Violation Detection

This detection leverages the pattern inventory from Step 2 to identify when new/changed code violates or duplicates established patterns. Use the same discovery approach as `pm7y-scss-patterns` skill.

| Issue | Pattern | Severity |
|-------|---------|----------|
| Duplicate mixin | New mixin does the same thing as existing mixin with different name | High |
| Duplicate variable | New variable serves same purpose as existing variable (e.g., two `$primary-color` and `$brand-color` both #3B82F6) | High |
| Duplicate utility class | New utility class provides same styles as existing utility | High |
| Naming convention violation | New class doesn't follow established naming pattern (BEM, OOCSS, etc.) | Medium |
| Variable value mismatch | Using hardcoded value when matching variable exists | Medium |
| Inconsistent mixin usage | Not using established mixin where it would apply | Low |

**Detection approach:**

1. **Duplicate mixins:** Compare new `@mixin` definitions against existing mixins. Two mixins are duplicates if they produce equivalent CSS output (same properties and values). Flag when a new mixin's body matches an existing mixin's body.

2. **Duplicate variables:** Compare new `$variable` definitions against existing variables. Flag when:
   - Two variables have the same value (exact match)
   - Two color variables are visually identical (hex/rgb equivalence)
   - Two spacing variables resolve to the same pixel value

3. **Duplicate utility classes:** Compare new class definitions against existing utilities. Flag when a new class has the same declarations as an existing utility class.

4. **Naming convention violations:** If the codebase uses BEM (`.block__element--modifier`), flag classes that don't follow this pattern. Similarly for other conventions detected in the inventory phase.

**Example violations:**

```scss
// DUPLICATE MIXIN - existing @mixin flex-center does the same thing
@mixin center-content {
  display: flex;
  justify-content: center;
  align-items: center;
}

// DUPLICATE VARIABLE - $color-primary already equals #3B82F6
$brand-blue: #3B82F6;

// DUPLICATE UTILITY - .flex-center already exists with same styles
.centered {
  display: flex;
  justify-content: center;
  align-items: center;
}

// NAMING CONVENTION VIOLATION - project uses BEM but this doesn't
.cardHeader { } // Should be .card__header
```

### Step 5: Pass Findings to pm7y-ralph-planner

After completing the analysis, invoke the `pm7y-ralph-planner` agent using the Task tool. Pass your findings as structured input so the planner can generate a proper TASKS.md with validation requirements and learnings tracking.

**Invoke pm7y-ralph-planner with this prompt:**

```
Generate a TASKS.md for CSS/SCSS refactoring.

## Goal
Fix CSS/SCSS issues identified during code review.

## Project Context
- **Branch:** [current branch name]
- **Files reviewed:** [count]
- **Issues found:** [X total] ([Y] high, [Z] medium, [W] low)
- **CSS Framework:** [Tailwind/Bootstrap/Custom/None]
- **Build command:** [detected build command, e.g., npm run build]
- **Lint command:** [detected lint command, if any]

## Findings

### HIGH Priority (should be fixed first)

- **[filepath]:[line]** - [Issue type]: [Description]. **Fix:** [Specific action to take].

[Repeat for each high priority finding]

### MEDIUM Priority

- **[filepath]:[line]** - [Issue type]: [Description]. **Fix:** [Specific action to take].

[Repeat for each medium priority finding]

### LOW Priority (fix if time permits)

- **[filepath]:[line]** - [Issue type]: [Description]. **Fix:** [Specific action to take].

[Repeat for each low priority finding]

## Notes
- Each fix should be verified by running the build/lint commands
- Verify changes don't break e