SKILL

---

name: xcode-api-diff-noise-cleaner description: > Analyze and triage Xcode SDK API diffs between betas for the dotnet/macios binding season. USE FOR: reviewing API diffs, classifying diffs as nothing or actionable, understanding xcode diff folder structure, cleaning up comment-only diffs, checking binding status, running make diff or make all. DO NOT USE FOR: writing C# bindings code (that's a separate task after triage).

Xcode API Diff Analysis

Knowledge skill for triaging Xcode SDK header diffs in the macios.wiki repo. Helps classify diffs as actionable API changes vs noise (comments, macros, formatting) and understand the binding status tracking system.

When to Use This Skill

• Reviewing raw framework diffs between Xcode beta versions
• Classifying whether a diff contains real API changes or only noise
• Understanding the xcode diff folder structure and Makefile workflow
• Cleaning up diffs that only contain comment/documentation changes
• Checking or updating the Bindings-Status table
• Running make diff or make all after Xcode updates

Repository Structure

macios.wiki/
├── Makefile                        # Drives diff generation and status table updates
├── xcode-diff.csharp               # Script that diffs SDK framework headers
├── update.csharp                   # Script that regenerates the Bindings-Status table
├── xcode{version}/
│   ├── xcode{version}-Bindings-Status.md   # Auto-generated status table (NEVER edit directly)
│   ├── b1/ b2/ b3/ rc/            # Per-beta/release diff directories
│   │   ├── iOS/
│   │   ├── tvOS/
│   │   ├── macOS/
│   │   └── MacCatalyst/
│   │       └── {Framework}-{platform}-xcode{ver}-{suffix}.md

Diff File Naming

{Framework}-{platform}-xcode{version}-{suffix}.md — e.g. AVKit-iOS-xcode26.4-b2.md

An empty diff file contains only #{Framework}.framework with no content below it.

Bindings-Status Table Conventions

The status table is generated — never edit it directly. Instead, edit the diff files and run make all -j.

Marker	Meaning
~~strikeout~~ + *nothing*	No new APIs — diff was reviewed and contains no actionable changes
bold + **???**	Has changes, not yet bound
[PR{number}]({url})	Binding work in progress or done
:warning:	Tracked via GitHub issue
-	Framework not available on that platform

Claiming Work

To mark a diff as "nothing": edit the diff file to contain only the framework header (remove all diff content), then make all -j regenerates the table with strikeout styling.

To claim a binding: add your PR link to the diff file following the existing format.

Classifying Diffs

When reviewing a diff, classify it into one of these categories:

✅ Actionable — Real API Changes

New or modified: classes, protocols, methods, properties, enums, typedefs, constants, or delegate methods. These need C# bindings.

❌ Noise — Mark as "Nothing"

Category 1: Comment/documentation-only changes

• /* ... */ → /// ... doc comment format rewrites
• Typo fixes in comments (e.g. "labelling" → "labeling")
• @c/@p → backtick formatting changes
• Reformatted multi-line doc comments

Category 2: Internal/build-system changes

• Preprocessor guard reordering (#ifdef, #elif, #endif)
• Macro renames that don't affect public API (e.g. TARGET_OS_LINUX_CLOUD → internal name)
• Swift sendability macros (NS_SWIFT_SENDABLE, NS_SWIFT_UNAVAILABLE)
• Header audit pragmas (#pragma clang assume_nonnull)
• extern "C" guard shuffling
• #include/#import reordering

Category 3: Truly empty

• Diff file has no content below the framework header. Already marked correctly.

⚠️ Mixed diffs: If a diff contains both noise AND real API changes, it is actionable. NEVER clean out the noise portions — the binding author WILL HANDLE everything.

❌ NEVER mark a diff as "nothing" if it contains any new method signatures, property declarations, enum values, class/protocol declarations, or typedef changes — even if surrounded by comment noise.

Makefile Workflow

Generating Diffs for a New Beta

1. Install both the old and new Xcode versions
2. Update Makefile variables: XCODE_OLD, XCODE_NEW, BRANCH, SUFFIX
3. Run make diff -j — generates per-framework, per-platform diff files
4. Run make all -j — regenerates the Bindings-Status table
5. Commit and push all new/updated files

After Reviewing/Claiming Diffs

Run make all -j to regenerate the status table, then commit.

Stop Signals

Stop analysis when:

• You've classified all diffs requested by the user
• You've determined whether a specific diff is actionable or noise
• The user has the information needed to decide next steps
• Do NOT start writing C# bindings — that's a separate task