swift-code-reviewer-skill 1.2.0 → 1.3.0

package/SKILL.md

@@ -1,797 +1,280 @@
 ---
 name: swift-code-reviewer
-description: >
-  Multi-layer code review agent for Swift and SwiftUI projects. Analyzes PRs,
-  diffs, and files across six dimensions: Swift 6+ concurrency safety, SwiftUI
-  state management and modern APIs, performance (view updates, ForEach identity,
-  lazy loading), security (force unwraps, Keychain, input validation), architecture
-  compliance (MVVM/MVI/TCA, dependency injection), and project-specific standards
-  from .claude/CLAUDE.md. Outputs structured reports with Critical/High/Medium/Low
-  severity, positive feedback, and prioritized action items with file:line
-  references and before/after code examples.
-
-  ALWAYS use this skill when the user says "review this PR", "review my code",
-  "review my changes", "check this file", "code review", "review against our
-  standards", "audit this codebase", "check code quality", mentions reviewing
-  any .swift file, asks about Swift best practices violations in existing code,
-  or wants feedback on Swift/SwiftUI code — even if they don't explicitly say
-  "code review". Also trigger when the user asks to "check if this follows our
-  coding standards", "review uncommitted changes", "review all ViewModels",
-  or mentions reviewing navigation, sheets, theming, or async patterns in Swift.
+description: "Perform thorough code reviews for Swift/SwiftUI code, including spec adherence (PR description + linked issues), code quality, architecture, performance, security, Swift 6+ best practices, project standards from .claude/CLAUDE.md, and meta-feedback on recurring patterns that suggest gaps in the agent's instructions. Use when reviewing PRs/MRs (especially AI-generated ones), performing quality audits, validating against original spec, or providing structured feedback with severity levels and improvement suggestions for both the code and the agent loop that produced it."
 ---
 
 # Swift/SwiftUI Code Review Skill
 
-## Overview
-
-This skill provides comprehensive code review capabilities for Swift and SwiftUI projects, combining Apple's best practices with project-specific coding standards. It performs multi-layer analysis covering code quality, architecture, performance, security, and maintainability.
-
-### Key Capabilities
-
-- **Project-Aware Reviews**: Reads `.claude/CLAUDE.md` and related architecture documents to validate against project-specific standards
-- **Multi-Layer Analysis**: Combines Swift 6+ best practices, SwiftUI patterns, performance optimization, and security checks
-- **Comprehensive Feedback**: Provides Critical/High/Medium/Low severity issues, positive feedback, and refactoring suggestions
-- **Integration with Existing Skills**: Leverages `swift-best-practices`, `swiftui-expert-skill`, and `swiftui-performance-audit` for domain expertise
-- **Actionable Output**: Structured feedback with file:line references, code examples, and prioritized action items
+Multi-layer review covering Swift 6+ concurrency, SwiftUI patterns, performance, security, architecture, and project-specific standards. Reads `.claude/CLAUDE.md` and outputs Critical/High/Medium/Low severity findings with `file:line` references and before/after code examples.
 
 ## When to Use This Skill
 
-Use this skill when you need to:
-
-- Review Pull Requests or Merge Requests for Swift/SwiftUI projects
-- Perform code quality audits on existing codebases
-- Validate code changes against project-specific standards
-- Analyze individual Swift/SwiftUI files for best practices
-- Review uncommitted git changes before committing
-- Assess architecture and maintainability of Swift code
-- Provide structured feedback to team members
-
-**Trigger patterns:**
-
 - "Review this PR"
-- "Review [filename].swift"
-- "Review my changes"
+- "Review my code" / "Review my changes" / "Review uncommitted changes"
 - "Code review for [component]"
-- "Check if this follows our coding standards"
-- "Review against .claude/CLAUDE.md"
-
-## Review Workflow
-
-The skill follows a **four-phase workflow** to ensure comprehensive and actionable feedback:
-
-### Phase 1: Context Gathering
-
-**Objective**: Understand the project context and scope of review
-
-1. **Read Project Guidelines**
-   - Load `.claude/CLAUDE.md` if it exists in the repository
-   - Read related architecture documents (e.g., `DependencyInjection-Architecture.md`, `Design System Structure.md`)
-   - Extract custom coding standards, patterns, and rules
-
-2. **Identify Review Scope**
-   - Determine files to review:
-     - User-specified files
-     - Git diff (uncommitted or PR/MR changes)
-     - Modified files in a specific directory
-   - Categorize changes by type (UI, logic, tests, configuration)
-
-3. **Gather File Context**
-   - Read all files that will be reviewed
-   - Understand the broader context (related files, dependencies)
-   - Identify the purpose and role of each component
-
-### Phase 2: Automated Analysis
-
-**Objective**: Run parallel checks across multiple quality dimensions
-
-Execute checks across **six core categories**:
-
-#### 1. Swift Best Practices
-
-Reference: `swift-best-practices` skill knowledge base
-
-- **Concurrency Safety**
-  - Actor isolation correctness
-  - MainActor usage for UI code
-  - Sendable conformance
-  - Data race prevention
-  - Async/await patterns
-
-- **API Design**
-  - Naming conventions (Swift API Design Guidelines)
-  - Parameter labels clarity
-  - Return type appropriateness
-  - Error handling (typed throws)
-
-- **Language Features**
-  - Availability attributes for new APIs
-  - Migration to Swift 6 features
-  - Avoiding deprecated patterns
-  - Proper use of optionals
-
-#### 2. SwiftUI Quality
-
-Reference: `swiftui-expert-skill` knowledge base
-
-- **State Management**
-  - Correct property wrapper selection (@Observable, @State, @Binding, @Environment)
-  - State ownership and data flow
-  - Avoiding unnecessary state
-  - View model patterns
-
-- **Modern API Usage**
-  - Replace deprecated APIs with modern equivalents
-  - Use latest SwiftUI features (iOS 17+, macOS 14+)
-  - Proper use of view modifiers
-  - Composition over inheritance
-
-- **View Composition**
-  - View extraction appropriateness
-  - Component reusability
-  - View hierarchy depth
-  - Subview organization
-
-- **Accessibility**
-  - Accessibility labels and hints
-  - VoiceOver support
-  - Dynamic Type support
-  - Keyboard navigation
-
-#### 3. Performance
-
-Reference: `swiftui-performance-audit` knowledge base
-
-- **View Optimization**
-  - Unnecessary view updates
-  - Heavy computation in body
-  - Equatable conformance for view models
-  - Lazy loading patterns
-
-- **List Performance**
-  - ForEach identity stability
-  - Cell reuse patterns
-  - Scroll performance
-  - Large dataset handling
-
-- **Layout Efficiency**
-  - Layout thrash detection
-  - GeometryReader overuse
-  - Frame calculations
-  - Animation performance
-
-- **Resource Management**
-  - Image loading and caching
-  - Memory leaks (retain cycles)
-  - Background task management
-  - Network request optimization
-
-#### 4. Security & Safety
-
-- **Data Validation**
-  - Input sanitization
-  - Type safety
-  - Boundary checking
-  - Force unwrap audit (avoid `!` and `as!`)
-
-- **Sensitive Data Handling**
-  - Password and token management
-  - Keychain usage for credentials
-  - Secure data transmission
-  - Log sanitization (no sensitive data in logs)
-
-- **Platform Security**
-  - Permission handling (camera, location, etc.)
-  - Network security (TLS, certificate pinning)
-  - Secure storage (UserDefaults vs Keychain)
-  - Code signing and entitlements
-
-#### 5. Architecture & Maintainability
-
-- **Project Architecture Compliance**
-  - Adherence to defined patterns (MVVM, MVI, TCA, etc.)
-  - Layer separation (View/ViewModel/Repository/UseCase)
-  - Dependency injection patterns
-  - Module boundaries
-
-- **Code Organization**
-  - File structure and naming
-  - Logical grouping
-  - Extension organization
-  - Protocol conformances
-
-- **Testability**
-  - Unit test coverage
-  - Test structure (Arrange-Act-Assert)
-  - Mock/stub usage
-  - Test isolation
-
-- **Documentation**
-  - DocC comments for public APIs
-  - Complex logic explanations
-  - Architecture decision records
-  - README and guides
-
-#### 6. Project-Specific Standards
-
-- **Custom Coding Standards**
-  - Validate against `.claude/CLAUDE.md` rules
-  - Check custom error handling patterns
-  - Verify project-specific naming conventions
-  - Validate testing requirements
-
-- **Design System Compliance**
-  - Use of design tokens
-  - Consistent spacing and typography
-  - Color palette adherence
-  - Component library usage
-
-- **Navigation Patterns**
-  - Coordinator pattern compliance
-  - Deep linking support
-  - State restoration
-  - Navigation flow consistency
-
-### Phase 3: Report Generation
-
-**Objective**: Aggregate findings into a structured, actionable report
-
-1. **Categorize Findings by Severity**
-   - **Critical**: Security vulnerabilities, data races, crashes, breaking changes
-   - **High**: Performance issues, anti-patterns, major architecture violations
-   - **Medium**: Code quality improvements, missing documentation, minor violations
-   - **Low**: Style inconsistencies, suggestions for refactoring
-
-2. **Include Positive Feedback**
-   - Acknowledge good practices and patterns
-   - Highlight excellent code quality
-   - Recognize proper use of modern APIs
-   - Note strong architecture decisions
-
-3. **Add Refactoring Suggestions**
-   - Proactive improvement opportunities
-   - Modernization suggestions
-   - Code simplification ideas
-   - Performance optimization hints
-
-4. **Group and Organize**
-   - Group by file, then by category
-   - Sort by severity within each file
-   - Include code location references (file:line)
-   - Provide specific code examples
-
-### Phase 4: Delivery
-
-**Objective**: Present findings in a clear, actionable format
-
-1. **Format as Structured Markdown**
-   - Executive summary with key metrics
-   - Severity breakdown
-   - File-by-file detailed findings
-   - Positive feedback section
-   - Prioritized action items
-
-2. **Include Code References**
-   - Exact file and line numbers (file.swift:123)
-   - Before/after code examples
-   - Links to relevant documentation
-   - Comparison with project guidelines
-
-3. **Provide Context**
-   - Explain _why_ something is an issue
-   - Reference best practices or standards
-   - Suggest specific fixes with examples
-   - Link to learning resources
-
-## Core Review Categories
-
-### 1. Swift Language Quality
-
-**What to Check:**
-
-- Concurrency patterns (actors, async/await, Sendable)
-- Error handling (typed throws, Result type)
-- Optionals handling (avoid force unwrapping)
-- Access control (public, internal, private, fileprivate)
-- Naming conventions (Swift API Design Guidelines)
-- Type inference vs explicit types
-- Value types vs reference types
-
-**Reference:** `references/swift-quality-checklist.md`
-
-### 2. SwiftUI Patterns
-
-**What to Check:**
-
-- Property wrapper selection and usage
-- State management patterns
-- View lifecycle understanding
-- Modern API usage (avoid deprecated)
-- View composition and extraction
-- Accessibility implementation
-- Preview configurations
-
-**Reference:** `references/swiftui-review-checklist.md`
-
-### 3. Performance Optimization
-
-**What to Check:**
-
-- View update optimization
-- ForEach identity and performance
-- Heavy work in view body
-- Image loading and caching
-- Memory management
-- Background task efficiency
-- Layout performance
-
-**Reference:** `references/performance-review.md`
-
-### 4. Security & Safety
-
-**What to Check:**
+- "Audit this codebase" / "Check code quality"
+- "Review against .claude/CLAUDE.md" / "Check if this follows our coding standards"
+- "Architecture review" / "Performance audit" / "Security review"
+- "Review this PR against the spec"
+- "Did the agent miss anything from issue #123?"
+- "What rules am I missing in CLAUDE.md based on this PR?"
+- "Review this AI-generated PR"
 
-- Force unwrap detection (`!`, `as!`, `try!`)
-- Input validation and sanitization
-- Sensitive data handling (passwords, tokens)
-- Keychain usage for credentials
-- Network security (HTTPS, certificate pinning)
-- Permission handling
-- Logging safety (no sensitive data in logs)
+## Workflow
 
-**Reference:** `references/security-checklist.md`
+### Phase 1 — Context Gathering
 
-### 5. Architecture & Design
+1. **Read the Spec**
+   - For PRs: `gh pr view <num> --json title,body,closingIssuesReferences,labels`
+   - For linked issues: `gh issue view <num> --json title,body,labels`
+   - For MRs: `glab mr view <num>` and `glab issue view <num>`
+   - Extract:
+     - Stated goal / problem being solved
+     - Explicit acceptance criteria (look for checkboxes, "should", "must", "Given/When/Then")
+     - Edge cases or non-goals mentioned
+     - Out-of-scope items
+   - If no PR/issue context is available, note this and fall back to inferring intent from the diff.
+2. Try to load `.claude/CLAUDE.md`.
+   - **If missing**: add a note to the report — _"No project standards file found — review uses default Apple guidelines"_ — then continue.
+3. Obtain the changeset: `git diff`, `git diff --cached`, or `gh pr diff <n>`.
+   - **If diff is empty**: stop and ask the user to specify files, a PR number, or a directory.
+4. Read each changed file plus key related files (imports, protocols it conforms to, corresponding test file if present).
 
-**What to Check:**
+### Phase 2 — Analysis
 
-- MVVM, MVI, TCA, or other architecture compliance
-- Dependency injection patterns
-- Separation of concerns
-- Module boundaries
-- Code organization
-- Testability
-- Documentation quality
+For each category, load the reference file before writing findings:
 
-**Reference:** `references/architecture-patterns.md`
+#### 0. Spec Adherence
 
-### 6. Project-Specific Standards
+Reference: `references/spec-adherence.md`
 
-**What to Check:**
+- **Requirement Coverage**
+  - Does each acceptance criterion map to a concrete code change?
+  - Are edge cases mentioned in the spec handled?
+  - Are tests covering the scenarios described?
+- **Scope Discipline**
+  - Flag changes outside the stated scope (scope creep)
+  - Flag unrelated refactors bundled into the PR
+- **Missing Work**
+  - TODOs, `fatalError("not implemented")`, empty function bodies
+  - Stubbed mocks that should be real implementations
+  - Acceptance criteria with no corresponding diff
+- **Intent Drift**
+  - Code solves a *similar* but different problem than stated
+  - Naming/structure suggests a different mental model than the spec
 
-- `.claude/CLAUDE.md` compliance
-- Custom architecture patterns
-- Design system usage
-- Navigation patterns
-- Error handling standards
-- Testing requirements
+1. **Swift Quality** — concurrency, error handling, optionals, naming → `references/swift-quality-checklist.md`; for concurrency findings also read `skills/swift-concurrency/references/sendable.md` and `actors.md`
+2. **SwiftUI Patterns** — property wrappers, state management, deprecated APIs → `references/swiftui-review-checklist.md`; for wrapper selection read `skills/swiftui-expert-skill/references/state-management.md`
+3. **Performance** — view body cost, ForEach identity, lazy loading, retain cycles → `references/performance-review.md`
+4. **Security** — force unwraps, Keychain vs UserDefaults, input validation, no secrets in logs → `references/security-checklist.md`
+5. **Architecture** — MVVM/MVI/TCA compliance, DI, testability → `references/architecture-patterns.md`
+6. **Project Standards** — validate against `.claude/CLAUDE.md` rules → `references/custom-guidelines.md`
 
-**Reference:** `references/custom-guidelines.md`
+For test file findings, consult `skills/swift-testing/references/test-organization.md`.
+For navigation/routing findings, consult `skills/swiftui-ui-patterns/references/navigationstack.md`.
 
-## Integration with Existing Skills
+### Phase 2.5 — Pattern Detection (for Agent Loop Feedback)
 
-This skill **references** (not duplicates) three foundational skills for domain expertise:
+**Objective**: Identify recurring issues that point to gaps in the agent's
+instructions, not just the code.
 
-### 1. swift-best-practices
+After collecting per-file findings, aggregate them:
 
-**When to Use:** Reviewing Swift language usage, concurrency patterns, API design, or Swift 6+ migration
+1. Group findings by rule (e.g., "force-unwrap", "deprecated NavigationView",
+   "missing @MainActor on UI mutation").
+2. Mark any rule that fires **≥2 times across the diff** as a recurring pattern.
+3. For each recurring pattern, draft a one-line rule suitable for
+   `.claude/CLAUDE.md` or an agent system prompt — written as a directive,
+   not a description.
+4. If the same recurring pattern appeared in past reviews (check git log of
+   `.claude/CLAUDE.md`), escalate priority — the existing rule isn't strong
+   enough or isn't being read.
 
-**What it Provides:**
+Threshold rationale: one occurrence is a slip; two is a pattern; three+ means
+the agent's instructions are silent on this and need an explicit rule.
 
-- Swift 6+ concurrency patterns (actors, async/await, Sendable)
-- API design guidelines compliance
-- Availability pattern validation
-- Breaking changes detection
-- Modern Swift feature adoption
+Reference: `references/agent-loop-feedback.md`.
 
-**How to Leverage:**
+### Phase 3 — Report
 
-- Read `~/.claude/skills/swift-best-practices/references/concurrency.md` for concurrency checks
-- Reference `swift6-features.md` for Swift 6 migration patterns
-- Use `api-design.md` for naming and parameter validation
+Group findings by file → sort by severity within each file → write prioritized action items.
 
-### 2. swiftui-expert-skill
+Severity: **Critical** (crash/data race/security hole) · **High** (anti-pattern/major arch violation) · **Medium** (quality/maintainability) · **Low** (style/suggestion).
 
-**When to Use:** Reviewing SwiftUI views, state management, or UI code
+Include one-sentence positive feedback where code is notably well-written. Never pad with generic praise.
 
-**What it Provides:**
+## Concrete Finding Examples
 
-- State management patterns (@Observable, @State, @Binding)
-- Modern SwiftUI API guidance (iOS 17+, macOS 14+)
-- View composition best practices
-- Property wrapper selection guide
-- Accessibility patterns
+### Force Unwrap → guard let (Critical)
 
-**How to Leverage:**
+**`LoginViewModel.swift:89`** — Current:
 
-- Read `~/.claude/skills/swiftui-expert-skill/references/state-management.md` for property wrapper checks
-- Reference `modern-apis.md` for deprecation detection
-- Use `view-composition.md` for component structure validation
-
-### 3. swiftui-performance-audit
-
-**When to Use:** Performance concerns identified or mentioned in PR description
-
-**What it Provides:**
-
-- View update optimization patterns
-- ForEach performance analysis
-- Layout thrash detection
-- Image handling best practices
-- Memory management
-
-**How to Leverage:**
-
-- Read `~/.claude/skills/swiftui-performance-audit/SKILL.md` for performance audit workflow
-- Reference performance-specific checks when reviewing view code
-- Apply recommendations from the skill to performance-sensitive paths
-
-### 4. swiftui-ui-patterns
-
-**When to Use:** Reviewing navigation architecture, sheet/modal routing, TabView setup, theming, async state management, focus handling, or API client patterns
-
-**What it Provides:**
-
-- Navigation architecture (route enums, RouterPath, centralized navigationDestination)
-- Sheet/modal routing (item-driven sheets, SheetDestination enum)
-- TabView with independent per-tab navigation history
-- Theming with semantic colors via `@Environment(Theme.self)`
-- Async state patterns (`.task(id:)`, LoadState enum, CancellationError handling)
-- Focus chaining with FocusField enum and `.onSubmit`
-- Lightweight API client pattern (closure-based structs, `.live()` / `.mock()` factories)
-
-**How to Leverage:**
-
-- Read `~/.claude/skills/swiftui-ui-patterns/references/navigation.md` for route enum and RouterPath checks
-- Reference `sheets-modals.md` for sheet routing validation
-- Use `theming.md` for semantic color enforcement
-
-**Integration Strategy:**
-
-1. Load relevant reference files from these skills as needed
-2. Apply their checklist items to the review
-3. Reference their documentation in feedback
-4. Avoid duplicating content—point to their knowledge base
-
-## Platform Support
-
-### GitHub Pull Requests
-
-Use `gh` CLI for fetching PR data:
-
-```bash
-# Get PR details
-gh pr view <PR-number>
+```swift
+let user = repository.currentUser!
+```
 
-# Get PR diff
-gh pr diff <PR-number>
+**Finding**: crashes if `currentUser` is `nil` (e.g., after sign-out race condition).
 
-# List PR files
-gh pr view <PR-number> --json files
+**Fix**:
 
-# Get PR comments
-gh pr view <PR-number> --json comments
+```swift
+guard let user = repository.currentUser else {
+    logger.error("currentUser nil — aborting login flow")
+    return
+}
 ```
 
-### GitLab Merge Requests
-
-Use `glab` CLI for fetching MR data:
+---
 
-```bash
-# Get MR details
-glab mr view <MR-number>
+### Missing @MainActor on UI-bound ViewModel (High)
 
-# Get MR diff
-glab mr diff <MR-number>
+**`FeedViewModel.swift:12`** — Current:
 
-# List MR files
-glab mr view <MR-number> --json
+```swift
+class FeedViewModel: ObservableObject {
+    @Published var posts: [Post] = []
 
-# Get MR comments
-glab mr note list <MR-number>
+    func load() async {
+        posts = try? await api.fetchPosts()  // ⚠️ mutates @Published off main thread
+    }
+}
 ```
 
-### Local Git Changes
-
-For uncommitted changes or manual review:
+**Finding**: `@Published` mutations must happen on the main actor in Swift 6 strict concurrency; this is a data race.
 
-```bash
-# Get uncommitted changes
-git diff
+**Fix**:
 
-# Get staged changes
-git diff --cached
+```swift
+@MainActor
+@Observable
+final class FeedViewModel {
+    var posts: [Post] = []
 
-# Get changes in specific files
-git diff -- path/to/file.swift
-
-# Get commit diff
-git show <commit-hash>
+    func load() async throws {
+        posts = try await api.fetchPosts()  // safe: whole class is @MainActor-isolated
+    }
+}
 ```
 
-## Output Format
+Also migrate from `ObservableObject`/`@Published` to `@Observable` (iOS 17+) — see `skills/swiftui-expert-skill/references/state-management.md`.
 
-The review report follows this structure:
+## Output Format
 
-````markdown
-# Code Review Report
+```
+# Code Review — <scope>
 
 ## Summary
+Files: N | Critical: N | High: N | Medium: N | Low: N
 
-- **Files Reviewed**: X
-- **Total Findings**: Y
-- **Critical**: 0
-- **High**: 2
-- **Medium**: 5
-- **Low**: 3
-- **Positive Feedback**: 8
-- **Refactoring Suggestions**: 4
-
-## Executive Summary
-
-[Brief overview of the changes and overall code quality]
-
----
-
-## Detailed Findings
-
-### File: Sources/Features/Login/LoginView.swift
-
-#### ✅ Positive Feedback
-
-1. **Excellent State Management** (line 23)
-   - Proper use of @Observable for view model
-   - Clean separation of concerns
-
-2. **Modern API Usage** (line 45)
-   - Using new SwiftUI APIs effectively
-   - Proper async/await integration
-
-#### 🔴 Critical Issues
-
-1. **Data Race Risk** (line 67)
-   - **Severity**: Critical
-   - **Category**: Concurrency
-   - **Issue**: Mutable state accessed from multiple actors without synchronization
-   - **Fix**:
-
-     ```swift
-     // Before
-     class LoginViewModel {
-         var isLoading = false
-     }
-
-     // After
-     @MainActor
-     class LoginViewModel: ObservableObject {
-         @Published var isLoading = false
-     }
-     ```
-
-   - **Reference**: swift-best-practices/references/concurrency.md
+## Spec Adherence
 
-#### 🟡 High Priority
+**Source**: PR #123 / Issue #456
 
-1. **Force Unwrap Detected** (line 89)
-   - **Severity**: High
-   - **Category**: Safety
-   - **Issue**: Force unwrapping optional can cause crash
-   - **Fix**:
+| Requirement | Status | Location |
+|-------------|--------|----------|
+| User can log in with email | ✅ Implemented | LoginView.swift:23 |
+| Show error on invalid credentials | ⚠️ Partial — missing 401 case | LoginViewModel.swift:67 |
+| Persist session in Keychain | ❌ Not implemented | — |
+| Rate limit retries | ❌ Not implemented | — |
 
-     ```swift
-     // Before
-     let user = fetchUser()!
-
-     // After
-     guard let user = fetchUser() else {
-         logger.error("Failed to fetch user")
-         return
-     }
-     ```
-
-   - **Reference**: Project coding standard (.claude/CLAUDE.md:45)
-
-#### 💡 Refactoring Suggestions
-
-1. **Extract Subview** (lines 120-150)
-   - Consider extracting login form into separate view
-   - Improves testability and reusability
+**Scope creep**: 1 unrelated change (UserSettings.swift refactor) — recommend
+splitting into a separate PR.
 
 ---
 
-## Prioritized Action Items
-
-### Must Fix (Critical/High)
-
-1. [ ] Fix data race in LoginViewModel.swift:67
-2. [ ] Remove force unwrap in LoginView.swift:89
+## <Filename.swift>
 
-### Should Fix (Medium)
+[Severity] **<Category>** (line N)
+Current: `<problematic snippet>`
+Fix: <explanation + corrected snippet>
 
-1. [ ] Add documentation to public APIs
-2. [ ] Improve error handling in NetworkService.swift
+## Positive Observations
+...
 
-### Consider (Low)
-
-1. [ ] Refactor login form into separate view
-2. [ ] Add more unit tests for edge cases
+## Prioritized Action Items
+- [Must fix] ...
+- [Should fix] ...
+- [Consider] ...
 
 ---
 
-## Positive Patterns Observed
-
-- Excellent use of @Observable for state management
-- Consistent adherence to project architecture (MVVM)
-- Comprehensive accessibility support
-- Strong error handling in most areas
-- Good test coverage for core functionality
-
-## References
+## Agent Loop Feedback
 
-- [Swift Best Practices](~/.claude/skills/swift-best-practices/SKILL.md)
-- [SwiftUI Expert Guide](~/.claude/skills/swiftui-expert-skill/SKILL.md)
-- [Project Coding Standards](.claude/CLAUDE.md)
-````
+Recurring patterns suggest the following rules are missing or under-emphasized
+in `.claude/CLAUDE.md`:
 
-## How to Use
-
-### Example 1: Review Specific File
-
-```
-User: "Review UserProfileView.swift"
+### Pattern: Force-unwraps (4 occurrences)
+**Files**: LoginView.swift:89, NetworkService.swift:34, UserRepo.swift:12,78
 
-Steps:
-1. Read .claude/CLAUDE.md for project standards
-2. Read UserProfileView.swift
-3. Run multi-layer analysis
-4. Provide structured feedback with severity levels and positive feedback
-```
+**Suggested rule**:
+> Never use `!`, `try!`, or `as!`. Use `guard let` with explicit early return,
+> typed throws, or `as?` with handling. Force-unwraps are crashes waiting to happen.
 
-### Example 2: Review Git Changes
+### Pattern: Deprecated NavigationView (2 occurrences)
+**Files**: ProfileView.swift:15, SettingsView.swift:22
 
-```
-User: "Review my uncommitted changes"
-
-Steps:
-1. Read .claude/CLAUDE.md
-2. Execute `git diff` to get changes
-3. Identify modified files
-4. Run analysis on each file
-5. Generate comprehensive review report
-```
+**Suggested rule**:
+> Use `NavigationStack` exclusively. `NavigationView` is deprecated as of iOS 16.
 
-### Example 3: Review Pull Request
+### Pattern: Business logic in View body (3 occurrences)
+**Files**: LoginView.swift:45, ProfileView.swift:78, FeedView.swift:34
 
-```
-User: "Review PR #123"
-
-Steps:
-1. Read .claude/CLAUDE.md
-2. Execute `gh pr view 123` and `gh pr diff 123`
-3. Identify changed files
-4. Read affected files for context
-5. Run multi-layer analysis
-6. Generate report with file:line references
+**Suggested rule**:
+> Views must not contain business logic, network calls, or data transformations.
+> Move all such work into the @Observable view model.
 ```
 
-### Example 4: Review Against Custom Guidelines
+Full templates and severity classification: `references/feedback-templates.md`.
 
-```
-User: "Review LoginViewModel.swift against our coding standards"
-
-Steps:
-1. Read .claude/CLAUDE.md
-2. Read related docs (DependencyInjection-Architecture.md)
-3. Read LoginViewModel.swift
-4. Validate against project-specific patterns
-5. Provide detailed feedback comparing with standards
-```
+## Companion Skills
 
-### Example 5: Review Multiple Files
+Full reference tables (all files, when to consult each): `references/companion-skills.md`.
 
-```
-User: "Review all ViewModels in the Features folder"
-
-Steps:
-1. Read .claude/CLAUDE.md
-2. Find all *ViewModel.swift files in Features/
-3. Analyze each against architecture patterns
-4. Provide file-by-file review
-5. Summarize common patterns and issues across all files
-```
+| Skill                          | Use for                                                    |
+| ------------------------------ | ---------------------------------------------------------- |
+| `skills/swiftui-expert-skill/` | SwiftUI state, Liquid Glass, macOS patterns, accessibility |
+| `skills/swift-concurrency/`    | Actors, Sendable, Swift 6 migration, async/await           |
+| `skills/swift-testing/`        | Swift Testing framework, test doubles, snapshots           |
+| `skills/swift-expert/`         | Swift 6+ patterns, protocols, memory, SPM                  |
+| `skills/swiftui-ui-patterns/`  | Navigation, sheets, theming, async state, grids            |
 
-### Example 6: Review Navigation / Routing Code
+## Platform Commands
 
+```bash
+# GitHub PR
+gh pr diff <n>
+gh pr view <n> --json files,comments
+
+# GitLab MR
+glab mr diff <n>
+glab mr view <n> --json
+
+# Local changes
+git diff             # unstaged
+git diff --cached    # staged
+git diff HEAD~1      # last commit
+git diff -- path/to/file.swift
 ```
-User: "Review our navigation setup and routing code"
-
-Steps:
-1. Read .claude/CLAUDE.md for project navigation patterns
-2. Read router/coordinator files (RouterPath, AppCoordinator, TabRouter)
-3. Read root views that set up NavigationStack and TabView
-4. Run navigation architecture checks:
-   - Route destinations use typed Hashable enum (not String/Int)
-   - RouterPath @Observable owns path (not ad-hoc @State)
-   - Single centralized .navigationDestination per stack
-   - .sheet(item:) preferred over .sheet(isPresented:) when model selected
-   - Multiple sheets use SheetDestination enum (not multiple booleans)
-   - Each tab has independent RouterPath (not shared)
-   - .onOpenURL at app root, not scattered in feature views
-5. Run async state checks:
-   - .task(id:) for input-driven async work
-   - CancellationError silenced
-   - LoadState<T> enum instead of multiple booleans
-6. Generate report with navigation-specific findings
-```
-
-## Resources
-
-This skill includes the following reference materials:
-
-### Core References
-
-- **review-workflow.md**: Detailed step-by-step review process, git commands, and diff parsing strategies
-- **feedback-templates.md**: Templates for positive/negative comments, severity classification guidelines
-
-### Quality Checklists
-
-- **swift-quality-checklist.md**: Swift 6+ concurrency, error handling, optionals, access control, naming
-- **swiftui-review-checklist.md**: Property wrappers, state management, modern APIs, view composition
-- **performance-review.md**: View updates, ForEach optimization, layout efficiency, resource management
-- **security-checklist.md**: Input validation, sensitive data, keychain, network security
-
-### Architecture & Customization
-
-- **architecture-patterns.md**: MVVM, MVI, TCA patterns, dependency injection, testing strategies
-- **custom-guidelines.md**: How to read and parse .claude/CLAUDE.md and project-specific standards
-
-## Best Practices
-
-1. **Always Read Project Guidelines First**
-   - Load `.claude/CLAUDE.md` before starting review
-   - Understand project-specific patterns and rules
-   - Merge project standards with Apple guidelines
-
-2. **Provide Balanced Feedback**
-   - Include positive feedback for good practices
-   - Don't just criticize—acknowledge what's done well
-   - Suggest improvements, not just problems
-
-3. **Be Specific and Actionable**
-   - Include exact file:line references
-   - Provide code examples for fixes
-   - Explain _why_ something is an issue
-   - Link to relevant documentation
-
-4. **Prioritize by Severity**
-   - Critical: Must fix before merge (security, crashes, data races)
-   - High: Should fix before merge (anti-patterns, performance issues)
-   - Medium: Address soon (code quality, documentation)
-   - Low: Consider for future (style, refactoring suggestions)
-
-5. **Leverage Existing Skills**
-   - Reference swift-best-practices for language patterns
-   - Use swiftui-expert-skill for UI code
-   - Apply swiftui-performance-audit for performance concerns
-   - Don't duplicate their content—point to their knowledge
-
-6. **Focus on Education**
-   - Explain the reasoning behind feedback
-   - Link to learning resources
-   - Help developers understand best practices
-   - Foster continuous improvement
 
 ## Limitations
 
-- Cannot execute code or run tests (can only analyze statically)
-- Cannot access external systems or APIs
-- Limited to analyzing code provided or accessible via git
-- Cannot detect runtime issues that require execution
-- Performance analysis is based on patterns, not profiling data
-
-For runtime analysis, recommend using Instruments or other profiling tools.
-
-## Version
-
-**Version**: 1.2.0
-**Last Updated**: 2026-04-10
-**Compatible with**: Swift 6+, SwiftUI (iOS 17+, macOS 14+, watchOS 10+, tvOS 17+, visionOS 1+)
+- Spec adherence checks require an accessible PR description or linked issue.
+  When reviewing local changes with no PR context, mark spec adherence as
+  "not assessed" rather than guessing intent.
+- Agent loop feedback assumes the code was AI-generated or AI-assisted. For
+  fully human-written code, recurring patterns are still useful but should be
+  framed as team coding standards rather than agent instructions.
+
+## Reference Files
+
+- `references/review-workflow.md` — detailed process, diff parsing, git commands
+- `references/feedback-templates.md` — output templates, severity classification
+- `references/spec-adherence.md` — parsing PR/issue specs, requirement coverage tables, scope creep classification
+- `references/agent-loop-feedback.md` — recurring-pattern threshold, directive phrasing, suggested-rule template
+- `references/swift-quality-checklist.md` — Swift 6+, concurrency, optionals, naming
+- `references/swiftui-review-checklist.md` — property wrappers, state, modern APIs
+- `references/performance-review.md` — view optimization, ForEach, resource management
+- `references/security-checklist.md` — input validation, Keychain, network security
+- `references/architecture-patterns.md` — MVVM/MVI/TCA, DI, testability
+- `references/custom-guidelines.md` — parsing `.claude/CLAUDE.md`
+- `references/companion-skills.md` — full companion skill tables