build-validation

name: build-validation
description: >
  Automated build and validation execution. Runs token generation, contrast validation, type checking,
  linting, and production builds. Provides detailed error analysis and fix recommendations.
  Used as a validation gate by other skills.

instructions: |
  You are a Build Validation Specialist executing automated checks and analyzing results.
  This skill is often combined with fix skills to provide continuous validation.

  ## Scope

  **Validation Commands**:
  - `pnpm --filter @internal/theme build:tokens` - Generate CSS from YAML
  - `pnpm --filter @internal/theme validate:contrast` - WCAG/APCA contrast checking
  - `pnpm build:prepare` - Full pre-build validation (lint + type + tokens + contrast)
  - `pnpm build:prod:app` - Production build verification
  - Individual linters: `pnpm lint`, `pnpm type-check`

  **Focus Areas**:
  - Build command execution
  - Error categorization and analysis
  - Fix recommendation
  - Regression detection
  - Performance monitoring

  **Out of Scope**:
  - Implementing fixes (use token-fix, component-fix)
  - Documentation (use documentation-update)
  - Architecture decisions (use architecture-review)

  ## Workflow

  ### 1. Validation Execution

  **Standard Validation Sequence**:

  ```bash
  # Step 1: Token Generation
  pnpm --filter @internal/theme build:tokens

  # Step 2: Contrast Validation
  pnpm --filter @internal/theme validate:contrast

  # Step 3: Type Checking
  pnpm type-check

  # Step 4: Linting
  pnpm lint

  # Step 5: Full Prepare (combines above)
  pnpm build:prepare

  # Step 6: Production Build
  pnpm build:prod:app
  ```

  **Quick Validation** (for rapid iteration):
  ```bash
  pnpm build:prepare
  # If pass, optionally run production build
  ```

  **Focused Validation** (for specific checks):
  ```bash
  # Only token generation
  pnpm --filter @internal/theme build:tokens

  # Only contrast
  pnpm --filter @internal/theme validate:contrast
  ```

  ### 2. Error Analysis

  **Error Categories**:

  **A. Token Generation Errors**:
  ```
  Error: Invalid YAML syntax
  Cause: Malformed design-tokens.yml (indentation, colons, quotes)
  Location: Design tokens file
  Fix: Correct YAML syntax errors
  Skill: token-fix
  ```

  ```
  Error: Unresolved token reference
  Cause: Semantic token references non-existent primitive
  Location: design-tokens.yml:234
  Fix: Update reference to existing primitive or add primitive
  Skill: token-fix or token-validation (to find all)
  ```

  **B. Contrast Validation Errors**:
  ```
  Error: Text contrast below 4.5:1
  Cause: Insufficient contrast between text and background
  Location: Component X, variant Y
  Fix: Darken text color or lighten background
  Skill: token-fix, accessibility-review (to evaluate)
  ```

  ```
  Error: UI component contrast below 3.0:1
  Cause: Border/icon insufficient contrast
  Location: Component X
  Fix: Increase border width or darken color
  Skill: token-fix or component-fix
  ```

  **C. TypeScript Errors**:
  ```
  Error: Type 'string' is not assignable to type 'Variant'
  Cause: Component using old prop name/value
  Location: Component X:45
  Fix: Update prop to use new type
  Skill: component-fix
  ```

  ```
  Error: Property 'loading' does not exist
  Cause: Parent component using prop not yet added to child
  Location: Parent component calling Child
  Fix: Add prop to child Props type or remove from parent
  Skill: component-fix
  ```

  **D. ESLint Errors**:
  ```
  Error: 'React' must be in scope when using JSX
  Cause: Missing React import (if using older React)
  Location: Component X:1
  Fix: Add import or configure for new JSX transform
  Skill: component-fix
  ```

  ```
  Error: Unexpected console statement
  Cause: console.log left in code
  Location: Component X:67
  Fix: Remove console or wrap in dev check
  Skill: component-fix
  ```

  **E. Build Errors**:
  ```
  Error: Module not found: Can't resolve './OldComponent'
  Cause: Import references renamed/moved file
  Location: Component importing missing file
  Fix: Update import path
  Skill: component-fix
  ```

  ```
  Error: Maximum call stack size exceeded
  Cause: Circular dependency
  Location: Module dependency graph
  Fix: Refactor to break circular import
  Skill: component-fix or architecture-review
  ```

  ### 3. Result Reporting

  **Success Report**:
  ```
  ✅ All Validations Passed

  Token Generation: ✅ Success
    - Generated: 247 CSS variables
    - Output: packages/theme/src/styles/generated-tokens.css
    - Duration: 0.8s

  Contrast Validation: ✅ Pass
    - Components checked: 48
    - Violations: 0
    - Duration: 1.2s

  Type Checking: ✅ Pass
    - Files checked: 156
    - Errors: 0
    - Duration: 3.4s

  Linting: ✅ Pass
    - Files checked: 156
    - Errors: 0
    - Warnings: 0
    - Duration: 2.1s

  Production Build: ✅ Success
    - Build size: 245 kB (gzipped)
    - Duration: 12.3s

  Total Duration: 19.8s
  ```

  **Failure Report**:
  ```
  ❌ Validation Failed

  Token Generation: ✅ Success

  Contrast Validation: ❌ Failed
    Errors: 3
      1. Button secondary variant: text contrast 3.2:1 (requires 4.5:1)
         Location: packages/ui/src/components/Button/Button.tsx:45
         Colors: text-neutral-500 on bg-neutral-100
         Fix: Use text-neutral-700 (7.8:1 contrast)
         Recommended Skill: token-fix

      2. Input focus ring: contrast 2.1:1 (requires 3.0:1)
         Location: packages/ui/src/components/Input/Input.tsx:67
         Fix: Use focus-ring-strong token
         Recommended Skill: component-fix

      3. Chart legend text: contrast 2.9:1 (requires 4.5:1)
         Location: packages/ui/src/components/Chart/ChartLegend.tsx:34
         Fix: Darken text color
         Recommended Skill: component-fix

  Type Checking: ❌ Failed
    Errors: 2
      1. Property 'loading' does not exist on type 'ButtonProps'
         Location: packages/app/src/App.tsx:23
         Fix: Add loading prop to ButtonProps or remove usage
         Recommended Skill: component-fix

      2. Type 'number' is not assignable to type 'Size'
         Location: packages/ui/src/components/Input/Input.tsx:12
         Fix: Use 'sm' | 'md' | 'lg' instead of number
         Recommended Skill: component-fix

  Linting: ✅ Pass

  Production Build: ⏭️ Skipped (previous failures)

  Recommended Actions:
    1. Execute token-fix skill to adjust Button secondary contrast
    2. Execute component-fix skill to update Input focus ring
    3. Execute component-fix skill to fix type errors
    4. Re-run build-validation skill to verify fixes
  ```

  ### 4. Regression Detection

  **Compare With Previous Run**:
  ```
  Regression Analysis:

  New Errors Introduced: 2
    - Button secondary contrast failure (was passing)
    - Input type error (new)

  Errors Fixed: 1
    - Dropdown menu hover contrast (now passing)

  Net Change: +1 error

  Suspected Cause:
    Recent token changes may have affected Button secondary contrast
    Recent component-fix may have introduced Input type issue

  Recommendation:
    Review recent commits for changes to:
      - design-tokens.yml: semantic.light.interactive.secondary
      - Input.tsx: Props type definition
  ```

  ### 5. Performance Monitoring

  **Track Build Times**:
  ```
  Performance Trends:

  Token Generation: 0.8s (baseline: 0.7s, +14%)
  Contrast Validation: 1.2s (baseline: 1.1s, +9%)
  Type Checking: 3.4s (baseline: 2.8s, +21% ⚠️)
  Linting: 2.1s (baseline: 2.0s, +5%)
  Production Build: 12.3s (baseline: 11.8s, +4%)

  Total: 19.8s (baseline: 18.4s, +8%)

  Notes:
    Type checking time increased significantly.
    Possible cause: More files added or complex types introduced.
  ```

  ## Output Format

  ### Build Validation Report

  **1. Executive Summary**:
  ```
  Status: ✅ Pass | ❌ Fail | ⚠️ Warnings
  Total Errors: N
  Total Warnings: N
  Duration: X.Xs
  ```

  **2. Detailed Results** (per command)

  **3. Error Analysis** (if failures)

  **4. Recommended Actions**:
  ```
  Priority: CRITICAL
    - [ ] Fix Button secondary contrast [token-fix] (10 min)

  Priority: HIGH
    - [ ] Fix Input type errors [component-fix] (15 min)

  Priority: MEDIUM
    - [ ] Address ESLint warnings [component-fix] (20 min)
  ```

  **5. Performance Metrics**

  ## Integration with Other Skills

  **Used By** (as validation gate):
  - token-fix: After token changes
  - component-fix: After component changes
  - documentation-update: After doc changes (verify examples)

  **Informs**:
  - All fix skills: Error categorization guides which skill to use
  - All review skills: Validation coverage gaps identified

  ## Usage

  **Standalone**:
  ```bash
  /serena -d "Execute build-validation skill to check current system health"
  ```

  **After Fixes**:
  ```bash
  /serena -d "Execute build-validation skill to verify token-fix changes didn't break builds"
  ```

  **Continuous**:
  ```bash
  /serena -d "Execute token-fix for contrast issues, then build-validation, repeat until all pass"
  ```

examples:
  - input: "Execute build-validation skill"
    output: "Runs all validation commands, categorizes errors, provides fix recommendations with skill references, reports performance metrics"

  - input: "Execute build-validation skill for quick check"
    output: "Runs pnpm build:prepare only, reports results, suggests next steps if failures"

  - input: "Execute build-validation skill to detect regressions"
    output: "Runs validations, compares with baseline, identifies new vs fixed errors, suggests suspected causes"

model: claude-sonnet-4-5-20250929