Breaking change analyzer for PF Core

[srambach]

Agent Name

find-breaking-change

Problem It Solves

Analyzes PatternFly pull requests for breaking changes to HTML and CSS (excluding React code). This agent helps PR reviewers and maintainers systematically identify changes that could break downstream consumers by examining:

• CSS class name changes (.pf-v6-c-*, .pf-v6-l-*, .pf-v6-u-*)
• CSS variable changes (--pf-v6-*, --pf-t--*)
• HTML structure modifications in .hbs files
• ARIA attribute changes
• Selector specificity changes

The agent categorizes findings by severity (High/Medium/Low) and provides migration recommendations.

Agent Markdown

---
description: Analyze a pull request for breaking changes to HTML and CSS
args:
  pr_number:
    description: The pull request number to analyze
    required: true
---

Analyze pull request #{{ pr_number }} for breaking changes to HTML and CSS following the PatternFly Breaking Changes Analyzer agent specification.

Focus on:
1. CSS class name changes (`.pf-v6-c-*`, `.pf-v6-l-*`, `.pf-v6-u-*`)
2. CSS variable changes (`--pf-v6-*`, `--pf-t--*`)
3. HTML structure changes in `.hbs` files
4. ARIA attribute changes
5. Selector specificity changes

**Analysis Workflow:**

### Step 1: Identify Changed Files
- Get list of changed `.scss` and `.hbs` files in the PR
- Focus on `src/patternfly/components/**`, `src/patternfly/layouts/**`, `src/patternfly/utilities/**`

### Step 2: Analyze SCSS Changes
For each changed `.scss` file:
1. Scan for removed/renamed classes matching `.pf-v6-[clu]-*`
2. Scan for removed/renamed CSS variables (`--pf-v6-*`, `--pf-t--*`)
3. Check variable default value changes (>20% is potentially breaking)
4. Identify selector structure changes

### Step 3: Analyze HBS Changes
For each changed `.hbs` file:
1. Check for removed elements
2. Check for changed element types (e.g., `<div>` → `<span>`)
3. Check for ARIA attribute changes
4. Check for required attribute changes

### Step 4: Categorize by Severity

**High Severity:**
- Renamed/removed CSS classes
- Removed CSS variables
- Changed element types
- Removed required elements

**Medium Severity:**
- Modifier class changes
- CSS variable value changes (>20%)
- ARIA attribute changes
- New required classes

**Low Severity:**
- Unit conversions (px → rem)
- Minor value adjustments (<20%)
- New optional classes/elements

### Step 5: Generate Report

Provide a detailed report with:
- Summary of changes
- Breaking changes categorized by severity
- Impact analysis
- Migration recommendations
- Files reviewed

Use the agent specification at `.claude/agents/find-breaking-change.md` for complete detection rules and PatternFly context.

Testing

How to Test

1. Clone the PatternFly repository
2. Place agent file at .claude/agents/find-breaking-change.md
3. Place command file at .claude/commands/find-breaking-change.md
4. Restart Claude Code
5. Run: /find-breaking-change pr_number=7985

Tested On

• Repository: patternfly/patternfly
• PR #7985: "fix(compass): restructure navigation to include home and search"

Test Results

Successfully identified:

• 2 Medium Severity changes (new HTML structure, CSS variable refactoring from shorthand to longhand)
• Multiple low-severity additions (new classes, icons)
• Provided migration recommendations
• Assessed backward compatibility
• Generated comprehensive markdown report

Observations

What worked:

• Systematically identified CSS variable refactoring (shorthand --Padding → longhand --PaddingBlockStart, etc.)
• Detected new HTML structure requirements
• Distinguished between breaking changes and backward-compatible additions
• Provided actionable migration guidance
• Correctly categorized severity levels
• Generated well-structured markdown report

What needs improvement:

• Could benefit from automated CSS variable value comparison (calculating % changes)
• Could integrate with semantic-release to suggest proper commit message format
• May need refinement for edge cases in different component types

Additional notes:

• Agent understands PatternFly's BEM naming conventions
• Recognizes PatternFly's two-layer CSS variable system (component vars + design tokens)
• Particularly useful for reviewing PRs before release to catch undocumented breaking changes
• Recommended to use as part of PR review process alongside manual review

Generated with Claude ;-D

[srambach]

Here's what it found for that particular example.

Breaking Changes Analysis: PR #7985

Summary

• PR Title: fix(compass): restructure navigation to include home and search
• Total Files Changed: 9 files
• SCSS Files: 1
• HBS Files: 5
• Potential Breaking Changes: 2 Medium Severity
• Overall Severity: Medium

---

High Severity Breaking Changes

None detected ✓

---

Medium Severity Breaking Changes

1. New Required HTML Elements: Compass Navigation Structure

Files:

• src/patternfly/components/Compass/compass-nav-content.hbs (new)
• src/patternfly/components/Compass/compass-nav-home.hbs (new)
• src/patternfly/components/Compass/compass-nav-main.hbs (new)
• src/patternfly/components/Compass/compass-nav-search.hbs (new)

Change Type: New DOM structure added to navigation
Impact: Consumers who were directly using the Compass navigation panel without the new wrapper elements may experience layout issues. The navigation now requires a more structured approach with home, main, and search sections.

Before:

{{#> compass-panel compass-panel--HasNoPadding=true}}
  {{#> tabs ...}}
  {{/tabs}}
{{/compass-panel}}

After:

{{#> compass-panel compass-panel--HasNoPadding=false}}
  {{#> compass-nav-content}}
    {{#> compass-nav-home}}...{{/compass-nav-home}}
    {{#> compass-nav-main}}
      {{#> tabs ...}}{{/tabs}}
    {{/compass-nav-main}}
    {{#> compass-nav-search}}...{{/compass-nav-search}}
  {{/compass-nav-content}}
{{/compass-panel}}

Migration: Wrap existing navigation content in the new compass-nav-content and compass-nav-main elements. Add optional compass-nav-home and compass-nav-search sections.

---

2. CSS Variable Changes: Padding Refactoring

File: src/patternfly/components/Compass/compass.scss
Change Type: CSS variable structure changed from shorthand to longhand

Impact: Consumers who override the Compass panel padding variable will need to update their overrides.

Variables Changed:

- --#{$compass}__panel--Padding: var(--pf-t--global--spacer--inset--page-chrome);
+ --#{$compass}__panel--PaddingBlockStart: var(--pf-t--global--spacer--inset--page-chrome);
+ --#{$compass}__panel--PaddingBlockEnd: var(--pf-t--global--spacer--inset--page-chrome);
+ --#{$compass}__panel--PaddingInlineStart: var(--pf-t--global--spacer--inset--page-chrome);
+ --#{$compass}__panel--PaddingInlineEnd: var(--pf-t--global--spacer--inset--page-chrome);

New Variables Added:

• --pf-v6-c-compass__nav--PaddingBlockStart
• --pf-v6-c-compass__nav--PaddingBlockEnd
• --pf-v6-c-compass__nav--PaddingInlineStart
• --pf-v6-c-compass__nav--PaddingInlineEnd
• --pf-v6-c-compass__nav-main--PaddingInlineStart
• --pf-v6-c-compass__nav-main--PaddingInlineEnd

Migration:

/* Old approach */
--pf-v6-c-compass__panel--Padding: 2rem;

/* New approach */
--pf-v6-c-compass__panel--PaddingBlockStart: 2rem;
--pf-v6-c-compass__panel--PaddingBlockEnd: 2rem;
--pf-v6-c-compass__panel--PaddingInlineStart: 2rem;
--pf-v6-c-compass__panel--PaddingInlineEnd: 2rem;

---

Low Severity / Non-Breaking Changes

1. New CSS Classes Added

File: src/patternfly/components/Compass/compass.scss

New classes added (backward compatible):

• .pf-v6-c-compass__nav-content - Container for navigation content
• .pf-v6-c-compass__nav-main - Main navigation section

These are additions only and do not break existing usage.

---

2. Icon Updates

File: src/patternfly/components/Compass/compass--icons.hbs

• Formatting changes to sparkle icon (whitespace only)
• New icons added: compass--icons--home and compass--icons--search

Impact: None - these are additions and formatting improvements.

---

3. Panel Padding Behavior Change

File: Demo usage in compass--card-view.hbs

- {{#> compass-panel compass-panel--HasNoPadding=true}}
+ {{#> compass-panel compass-panel--HasNoPadding=false}}

Impact: Minor - the panel now has padding by default, but this is controlled by the panel parameter.

---

Recommendations

1. ✓ No Breaking Change Tag Required: While there are structural changes, they are primarily additions and improvements to the Compass component. Existing usage should continue to work.

2. Documentation Update Needed:

   • Document the new navigation structure (compass-nav-content, compass-nav-home, compass-nav-main, compass-nav-search)
   • Update examples to show the recommended navigation pattern
   • Document the new CSS variables for padding customization

3. Migration Guide (if consumers are customizing Compass):

   • Update any custom CSS that overrides --pf-v6-c-compass__panel--Padding to use the longhand properties
   • Consider adopting the new navigation structure for better semantic markup

4. Backward Compatibility: The changes are mostly backward compatible. Existing Compass implementations will continue to work, but won't have the new home/search features without updating to the new structure.

5. Communication: This is a fix rather than a breaking change. The PR title correctly identifies it as a fix. Consider mentioning in release notes as an "Enhancement" with migration notes for those customizing padding.

---

Files Reviewed

• ✓ src/patternfly/components/Compass/compass--icons.hbs
• ✓ src/patternfly/components/Compass/compass-nav-content.hbs (new)
• ✓ src/patternfly/components/Compass/compass-nav-home.hbs (new)
• ✓ src/patternfly/components/Compass/compass-nav-main.hbs (new)
• ✓ src/patternfly/components/Compass/compass-nav-search.hbs (new)
• ✓ src/patternfly/components/Compass/compass.scss
• ✓ src/patternfly/components/Compass/examples/Compass.md
• ✓ src/patternfly/demos/Compass/compass--card-view.hbs
• ✓ src/patternfly/demos/Compass/examples/Compass.md

---

Additional Notes

Accessibility Maintained

• New home and search buttons include proper aria-label attributes
• Icon SVGs maintain aria-hidden="true"
• No ARIA roles or required attributes were removed

Design Pattern Improvement

This PR improves the Compass navigation structure by:

• Adding dedicated home and search navigation areas
• Better semantic HTML structure
• More granular control over navigation padding

React Component Impact

The PatternFly React team should be notified of the new HTML structure to determine if the React Compass component needs updates to support the new navigation pattern.

[srambach]

I've updated the agent to better handle looking at just the changes in a PR rather than everything since the last release.

find-breaking-change.md