[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.

Prerequisites: MUST READ before executing:

• .claude/skills/shared/scan-and-update-reference-doc-protocol.md

• .claude/skills/shared/understand-code-first-protocol.md

Quick Summary

Goal: Scan project stylesheets and populate docs/project-reference/scss-styling-guide.md with BEM methodology usage, SCSS architecture, mixins/variables inventory, theming patterns, responsive breakpoints, and design token conventions.

Workflow:

• Read — Load current target doc, detect init vs sync mode

• Scan — Discover styling patterns via parallel sub-agents

• Report — Write findings to external report file

• Generate — Build/update reference doc from report

• Verify — Validate file paths and variable names exist

Key Rules:

• Generic — works with any CSS methodology (SCSS, Less, CSS Modules, Tailwind, styled-components)

• Detect styling approach first, then scan for approach-specific patterns

• Every example must come from actual stylesheets with file:line references

• Focus on project conventions, not generic CSS tutorials

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Scan SCSS Styling

Phase 0: Read & Assess

• Read docs/project-reference/scss-styling-guide.md

• Detect mode: init (placeholder) or sync (populated)

• If sync: extract existing sections and note what's already well-documented

Phase 1: Plan Scan Strategy

Detect styling approach:

• *.scss files → SCSS/Sass (check for BEM patterns, mixins, variables)

• *.less files → Less

• *.module.css / *.module.scss → CSS Modules

• tailwind.config.* → Tailwind CSS

• styled-components / emotion in package.json → CSS-in-JS

• Multiple approaches → document each

Identify styling infrastructure:

• Global styles entry point (styles.scss , global.css )

• Theme files (CSS custom properties, SCSS theme maps)

• Design token files (JSON tokens, CSS variables)

• Shared mixins/variables directories

Use docs/project-config.json styling section if available.

Phase 2: Execute Scan (Parallel Sub-Agents)

Launch 2 Explore agents in parallel:

Agent 1: SCSS Architecture & Variables

• Glob for **/*.scss (or detected extension) to map stylesheet tree

• Find the main/global stylesheet entry points and their @import/@use chains

• Grep for SCSS variables ($variable-name ) — inventory the most-used ones

• Find mixin definitions (@mixin ) and their usage frequency

• Discover function definitions (@function )

• Find design token files (CSS custom properties --token-name , JSON token files)

• Look for breakpoint definitions and responsive mixins

Agent 2: BEM Patterns & Theming

• Grep for BEM class patterns in templates/HTML (block__element--modifier )

• Find BEM naming conventions (separator style, nesting depth)

• Discover theming patterns (light/dark, CSS custom properties, theme switching)

• Find component-scoped vs global style patterns

• Look for z-index management (variables, scale)

• Find animation/transition conventions

• Identify color palette definitions and usage patterns

Write all findings to: plans/reports/scan-scss-styling-{YYMMDD}-{HHMM}-report.md

Phase 3: Analyze & Generate

Read the report. Build these sections:

Target Sections

Section Content

BEM Methodology BEM naming convention used, nesting rules, examples from actual components

SCSS Architecture File organization, import chain, global vs component styles

Mixins & Variables Inventory table: mixin/variable name, purpose, file location, usage count

Theming Theme approach (CSS vars, SCSS maps, etc.), how to add/modify themes

Responsive Patterns Breakpoint definitions, responsive mixins, mobile-first vs desktop-first

Design Tokens Token naming convention, categories (color, spacing, typography), file locations

Color Palette Color variables/tokens with their hex values and semantic names

Z-Index Scale Z-index variable definitions and layering conventions

Content Rules

• Show actual SCSS/CSS snippets (5-15 lines) from the project with file:line references

• Include variable/mixin inventory tables with usage counts

• Use color swatches or hex values for color palette documentation

• Show BEM examples from real components (not fabricated)

Phase 4: Write & Verify

• Write updated doc with <!-- Last scanned: YYYY-MM-DD --> at top

• Verify: 5 stylesheet file paths exist (Glob check)

• Verify: variable names in examples match actual SCSS definitions

• Report: sections updated, variables counted, theming approach documented

IMPORTANT Task Planning Notes (MUST FOLLOW)

• Always plan and break work into many small todo tasks using TaskCreate

• Always add a final review todo task to verify work quality and identify fixes/enhancements