swift-code-reviewer-skill 1.2.1 → 1.4.0

package/examples/gemini-isowords-review.md

@@ -0,0 +1,207 @@
+# Code Review — pointfreeco/isowords
+
+**Agent**: Google Gemini CLI with swift-code-reviewer-skill  
+**Scope**: `Sources/` (Start using IssueReporting)  
+**Commit**: [`c727d3a`](https://github.com/pointfreeco/isowords/commit/c727d3a7c49cf0c98f2fa4f24c562f81e30165f7)
+
+---
+
+## Summary
+
+Files: 5 | Critical: 0 | High: 1 | Medium: 3 | Low: 2
+
+---
+
+## Spec Adherence
+
+**Source**: commit message — "Start using IssueReporting. (#205)"
+
+| Requirement                                                | Status                                             | Location                                                   |
+| ---------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------- |
+| Replace `fatalError`/`assertionFailure` with `reportIssue` | ✅ Done                                            | multiple files                                             |
+| Migrate `preconditionFailure` to `reportIssue`             | ⚠️ Partial — 2 call sites missed                   | GameFeature/GameView.swift:134, AudioPlayerClient.swift:67 |
+| No behavioral change for release builds                    | ✅ Confirmed — `reportIssue` is a no-op in release | —                                                          |
+| Tests updated to assert `reportIssue` calls                | ❌ Not implemented — no test changes in diff       | —                                                          |
+
+**Missing work**: Two `preconditionFailure` sites not migrated; no test assertions added for
+`reportIssue` invocations (IssueReporting provides `withExpectedIssue` for exactly this).
+
+---
+
+## GameFeature/GameView.swift
+
+**High** **SwiftUI Patterns** (line 89)
+
+Current:
+
+```swift
+NavigationView {
+    WithViewStore(self.store) { viewStore in
+        GameBoardView(store: self.store)
+    }
+}
+```
+
+Finding: `NavigationView` is deprecated as of iOS 16. `WithViewStore` is the older TCA
+observation pattern — isowords targets iOS 16+ and should use `NavigationStack` with
+the `@Bindable` store observation available in TCA 1.x.
+
+Fix:
+
+```swift
+NavigationStack {
+    GameBoardView(store: self.store)
+}
+```
+
+And in the view body, replace `WithViewStore` reads with direct `store.someState` access
+via `@Bindable var store: StoreOf<GameFeature>`.
+
+---
+
+**Medium** **SwiftUI Patterns** (line 134)
+
+Current:
+
+```swift
+preconditionFailure("Unexpected game mode: \(mode)")
+```
+
+Finding: This `preconditionFailure` was not migrated to `reportIssue` in this PR. The PR
+description states the goal is to migrate all hard crashes to `reportIssue`. In production,
+`preconditionFailure` will crash the app; `reportIssue` would log the issue and allow the
+app to degrade gracefully.
+
+Fix:
+
+```swift
+reportIssue("Unexpected game mode: \(mode)")
+return  // or a safe default path
+```
+
+---
+
+## AudioPlayerClient.swift
+
+**Medium** **Swift Quality** (line 67)
+
+Current:
+
+```swift
+preconditionFailure("AudioPlayerClient not implemented")
+```
+
+Finding: Same as above — not migrated to `reportIssue`. Additionally, `"not implemented"`
+as a crash message suggests this may be a stub that should be a real implementation or at
+least a `TODO` tracked in the issue tracker.
+
+Fix:
+
+```swift
+reportIssue("AudioPlayerClient: \(#function) not implemented")
+```
+
+---
+
+## AppFeature/AppReducer.swift
+
+**Medium** **Architecture** (line 201)
+
+Current:
+
+```swift
+case .game(.delegate(.gameOver)):
+    guard let result = state.game?.gameResult else {
+        reportIssue("gameOver delegate action fired without a game result")
+        return .none
+    }
+```
+
+Finding: The `reportIssue` call is correct and well-placed. However, the `guard` falls
+through to `.none` silently — callers observing the game-over flow will see no state
+change and no indication that the invariant was violated. Consider adding a state flag
+or `.send` to surface the degraded state to the UI.
+
+Fix: After `reportIssue`, set a recoverable error state:
+
+```swift
+reportIssue("gameOver delegate action fired without a game result")
+state.errorBanner = "Something went wrong. Please restart the game."
+return .none
+```
+
+---
+
+## Tests/GameFeatureTests/GameViewTests.swift
+
+**Low** **Swift Quality** (line 12)
+
+Current:
+
+```swift
+import XCTest
+@testable import GameFeature
+```
+
+Finding: isowords has started migrating to Swift Testing (visible in other test files in
+this repo). New test files should use `import Testing` unless XCTest-specific APIs are
+required. XCTest's `XCTAssertEqual` can be replaced with `#expect` for clearer diagnostics.
+
+Fix:
+
+```swift
+import Testing
+@testable import GameFeature
+```
+
+---
+
+## Positive Observations
+
+The adoption of `IssueReporting` is architecturally sound — replacing hard crashes with
+soft issue reports significantly improves testability, since `withExpectedIssue` lets tests
+assert that invalid states are reported rather than crashing the test suite.
+
+`AppReducer.swift` correctly uses `reportIssue` (not `assertionFailure`) in the newly
+migrated call sites, demonstrating consistent application of the pattern.
+
+---
+
+## Prioritized Action Items
+
+- [Must fix] Migrate remaining `preconditionFailure` calls to `reportIssue` (GameView.swift:134, AudioPlayerClient.swift:67)
+- [Should fix] Add `withExpectedIssue` test assertions for newly reportable error paths
+- [Should fix] Replace deprecated `NavigationView` + `WithViewStore` with `NavigationStack` + `@Bindable` (GameView.swift:89)
+- [Consider] Surface degraded state to UI after `reportIssue` in AppReducer (AppReducer.swift:201)
+- [Consider] Migrate GameViewTests to Swift Testing framework
+
+---
+
+## Agent Loop Feedback
+
+### Pattern: Incomplete migration — `preconditionFailure` not replaced (2 occurrences)
+
+**Files**: GameFeature/GameView.swift:134, AudioPlayerClient.swift:67
+
+**Suggested rule for `GEMINI.md`**:
+
+> When migrating crash calls (`fatalError`, `preconditionFailure`, `assertionFailure`) to
+> `reportIssue`, search the entire diff for remaining instances before marking the PR complete.
+> Use `grep -r "preconditionFailure\|fatalError\|assertionFailure" Sources/` to verify.
+
+### Pattern: No tests added for new `reportIssue` call sites (covers 3+ sites)
+
+**Files**: AppFeature/AppReducer.swift, GameFeature/GameView.swift, AudioPlayerClient.swift
+
+**Suggested rule for `GEMINI.md`**:
+
+> Every new `reportIssue` call site must have a corresponding `withExpectedIssue { }` test.
+> IssueReporting is only valuable if tests verify the reports fire — otherwise it is
+> indistinguishable from a no-op.
+
+---
+
+_Representative demonstration. Generated against commit
+[`c727d3a`](https://github.com/pointfreeco/isowords/commit/c727d3a7c49cf0c98f2fa4f24c562f81e30165f7)
+of [pointfreeco/isowords](https://github.com/pointfreeco/isowords).
+Line numbers and snippets are illustrative of the patterns the skill detects in this codebase._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swift-code-reviewer-skill",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Claude Code skill for comprehensive Swift/SwiftUI code reviews with multi-layer analysis",
   "keywords": [
     "claude",
@@ -40,6 +40,8 @@
   },
   "files": [
     "bin/",
+    "core/",
+    "examples/",
     "references/",
     "skills/",
     "templates/",
@@ -49,6 +51,9 @@
     "CONTRIBUTING.md",
     "CHANGELOG.md"
   ],
+  "dependencies": {
+    "@inquirer/prompts": "^7"
+  },
   "engines": {
     "node": ">=16.0.0"
   }

package/references/agent-loop-feedback.md

@@ -0,0 +1,148 @@
+# Agent Loop Feedback Reference
+
+When the code under review was generated by an AI agent, recurring mistakes
+are not just *code* problems — they are *instruction* problems. This document
+defines how the reviewer aggregates per-finding signals into rule suggestions
+that can be added to `.claude/CLAUDE.md` or an agent system prompt to prevent
+the same class of issue next time.
+
+---
+
+## 1. The ≥2 Threshold
+
+A single instance of a mistake is a slip. Two is a pattern. Three or more
+means the agent's instructions are silent on the topic and need an explicit
+rule.
+
+Rules of thumb:
+
+| Occurrences in diff | Treatment                                                                         |
+| ------------------- | --------------------------------------------------------------------------------- |
+| 1                   | Per-file finding only. Do not surface in Agent Loop Feedback.                     |
+| 2                   | Recurring pattern. Suggest a rule. Mark priority **medium**.                      |
+| 3+                  | Strong signal. Suggest a rule. Mark priority **high**.                            |
+| 2+ across PRs       | If the same rule has been suggested before (see §3), escalate to **high**.        |
+
+Count occurrences by **rule**, not by raw findings. For example, four force-unwrap
+findings in different files count as four occurrences of the rule
+*"never force-unwrap"*, not four separate rules.
+
+---
+
+## 2. Phrasing Rules as Directives
+
+Rules go in an instruction file the agent will *read*. Write them so the
+reader knows what to do without further interpretation.
+
+### Strong forms
+
+- **Never X.** — bans an action outright. Best for safety/security/crashes.
+- **Always Y.** — mandates an action. Best for required patterns.
+- **Prefer X over Y.** — gives a default with an implicit escape hatch. Best
+  for stylistic or modernization rules.
+- **Use X. Y is deprecated / forbidden.** — adds the *why* in five words.
+
+### Weak forms (avoid)
+
+- **"Try to..."** — agents will skip it under pressure.
+- **"It's a good idea to..."** — descriptive, not directive.
+- **"Consider..."** — fine in code review prose, useless as a rule.
+- **"X is bad"** — diagnostic, not prescriptive. Doesn't tell the agent what
+  to do instead.
+
+### Examples
+
+| Weak                                                   | Strong                                                                                              |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Force unwraps are dangerous.                           | Never use `!`, `try!`, or `as!`. Use `guard let` with an early return, typed throws, or `as?`.      |
+| It's better to use `NavigationStack`.                  | Use `NavigationStack` exclusively. `NavigationView` is deprecated as of iOS 16.                     |
+| Try to keep views simple.                              | Views must not contain business logic, network calls, or data transformations. Move all such work into the `@Observable` view model. |
+| Make sure UI updates happen on the main thread.        | Always annotate types that mutate `@Observable`/`@Published` state with `@MainActor`.               |
+| Don't put secrets in logs.                             | Never log values from `KeychainService`, `URLRequest.httpBody`, or types annotated `@Sensitive`.    |
+
+A good rule answers three questions in one sentence: *what is forbidden*,
+*what is the alternative*, and (briefly) *why*.
+
+---
+
+## 3. Checking Past Reviews
+
+Before suggesting a rule, check whether something similar was already
+suggested. If yes, the existing wording is not landing — escalate priority
+and consider strengthening the wording rather than restating it.
+
+```bash
+# Has anyone touched the rules file recently, and how?
+git log --oneline --follow .claude/CLAUDE.md
+git log -p --follow .claude/CLAUDE.md | grep -i "<keyword from new rule>"
+
+# Search for existing wording on the topic
+grep -in "force.unwrap\|navigationview\|mainactor" .claude/CLAUDE.md
+```
+
+If a rule on the same topic exists:
+
+1. Quote the current rule in the suggestion block.
+2. Explain why it is not preventing the pattern (too soft, too narrow,
+   buried, conditional).
+3. Propose a replacement, not an addition.
+
+If no rule exists, propose adding one in the most relevant section
+(`Concurrency`, `SwiftUI`, `Security`, `Architecture`, etc.).
+
+---
+
+## 4. Suggested-Rule Block — Template
+
+One block per recurring pattern. Place all blocks under a single
+`## Agent Loop Feedback` heading at the bottom of the report.
+
+```markdown
+### Pattern: <short name> (<N> occurrences)
+**Files**: <file:line>, <file:line>, ...
+
+**Suggested rule**:
+> <One-sentence directive in strong form. What is forbidden, what to do
+> instead, and one-clause why.>
+
+**Existing rule** (if any): <quote, with line reference into `.claude/CLAUDE.md`>
+
+**Why it's not landing** (only if existing rule): <too soft / too narrow / buried / etc.>
+
+**Priority**: <medium | high>
+```
+
+Worked example:
+
+```markdown
+### Pattern: Force-unwraps (4 occurrences)
+**Files**: LoginView.swift:89, NetworkService.swift:34, UserRepo.swift:12, UserRepo.swift:78
+
+**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.
+
+**Existing rule**: _.claude/CLAUDE.md:42_ — "Avoid force unwrapping when possible."
+
+**Why it's not landing**: "When possible" gives the agent a built-in opt-out.
+The replacement above bans the syntax outright and names the alternatives.
+
+**Priority**: high
+```
+
+---
+
+## 5. Human-Authored Code
+
+If the PR was written by a human (no AI assistance disclosed, no agent
+session metadata in commit messages), the same recurring patterns are still
+useful — but frame them as **team coding standards**, not agent instructions:
+
+- Replace "Suggested rule for the agent" with "Suggested team standard".
+- Drop the "Why it's not landing" clause; humans benefit more from a short
+  rationale than from instruction-tuning analysis.
+- Leave the directive phrasing intact — strong forms read better in human
+  style guides too.
+
+When unsure whether the code is AI-generated, default to the team-standards
+framing.

package/references/spec-adherence.md

@@ -0,0 +1,157 @@
+# Spec Adherence Reference
+
+This document describes how the reviewer extracts the *intent* of a change from
+its PR description and linked issues, and how it then judges whether the code
+delivers on that intent. Spec adherence runs before the language- and
+framework-level checks: a clean diff that misses the point shouldn't pass.
+
+---
+
+## 1. Parsing `gh` / `glab` JSON Output
+
+Always prefer the JSON output of the platform CLI over scraping the web UI —
+it is stable, scriptable, and includes linked-issue metadata.
+
+### GitHub
+
+```bash
+# PR body, title, labels, and the issues this PR closes
+gh pr view <num> --json title,body,closingIssuesReferences,labels
+
+# Linked issue (one per closing reference)
+gh issue view <num> --json title,body,labels
+
+# Reviewer-friendly summary in one shot
+gh pr view <num> --json title,body,closingIssuesReferences \
+  --jq '{title, body, issues: [.closingIssuesReferences[].number]}'
+```
+
+Fields to read:
+
+| Field                       | Use                                               |
+| --------------------------- | ------------------------------------------------- |
+| `title`                     | Short statement of intent — start here.           |
+| `body`                      | Acceptance criteria, scope, non-goals.            |
+| `closingIssuesReferences`   | Numbers of issues that this PR will close.        |
+| `labels`                    | `bug`, `feature`, `tech-debt` shape expectations. |
+
+### GitLab
+
+```bash
+glab mr view <num>           # human-readable; pipe to less
+glab mr view <num> --output json
+glab issue view <num> --output json
+```
+
+GitLab's MR description and linked issues serve the same role as GitHub's PR
+body and `closingIssuesReferences`.
+
+---
+
+## 2. Finding Acceptance Criteria
+
+Acceptance criteria are rarely labeled as such. Look for these patterns, in
+roughly this order:
+
+1. **Markdown checkboxes** — `- [ ] ...` or `- [x] ...`. The most reliable
+   signal. Each box is a discrete requirement.
+2. **Gherkin / Given-When-Then** — phrases starting with `Given`, `When`,
+   `Then`, or `And`. Common in BDD-flavored teams.
+3. **Modal verbs** — `must`, `should`, `shall`, `will`, `needs to`. Each
+   sentence is a candidate requirement; `must`/`shall` outrank `should`.
+4. **Numbered or bulleted lists** under headings like `Acceptance Criteria`,
+   `Requirements`, `Scope`, `Goals`, `What this PR does`.
+5. **"Closes #N" / "Fixes #N"** — pull the linked issue and repeat 1–4 there.
+
+If the PR has none of the above, treat the **title** as the single requirement
+and note the lack of explicit criteria in the report.
+
+---
+
+## 3. Handling PRs With No Description
+
+A blank or near-blank description is itself a finding. Do not invent intent.
+
+1. Note in the report: _"PR description is empty / minimal — spec adherence
+   inferred from diff and commit messages, may be incomplete."_
+2. Use, in order: linked issues, commit messages (`git log <base>..HEAD`),
+   branch name, file paths touched.
+3. List every inferred requirement explicitly so the author can correct any
+   misreading, prefixed with `(inferred)`.
+4. Do not penalize the diff for failing to satisfy a requirement that was
+   only inferred — flag the missing description instead.
+
+---
+
+## 4. Scope Creep vs. Legitimate Adjacent Fixes
+
+Not every out-of-spec change is scope creep. Use this rubric:
+
+| Change type                                                                  | Verdict                               |
+| ---------------------------------------------------------------------------- | ------------------------------------- |
+| Touches a file required by the spec, fixes an obvious nearby bug, < ~10 LOC  | **Allow** — note it; don't flag.      |
+| Renames or restructures a file the spec requires editing                     | **Allow if minimal**, otherwise flag. |
+| Drive-by formatting / style changes across many files                        | **Flag** — recommend separate PR.     |
+| Refactor of a module unrelated to the spec                                   | **Flag** — scope creep.               |
+| New feature not mentioned anywhere in spec                                   | **Flag** — scope creep, must justify. |
+| Dependency version bumps                                                     | **Flag** — separate PR by convention. |
+| Test additions for the spec'd code                                           | **Allow** — expected.                 |
+| Test additions for unrelated existing code                                   | **Allow but note** — usually welcome. |
+
+When flagging scope creep, always recommend the concrete remediation
+("split out into a follow-up PR" or "move to a separate commit if the team
+allows partial review").
+
+---
+
+## 5. Intent Drift
+
+The trickier failure mode: the diff *runs* but solves a subtly different
+problem than the spec. Symptoms:
+
+- Naming uses different domain terms than the spec (e.g., spec says
+  "session", code says "token").
+- Data flow contradicts the spec's mental model (e.g., spec says the server
+  is the source of truth, code caches and treats local as authoritative).
+- Edge cases the spec called out are silently excluded by an early `return`.
+- The PR title says "fix" but the diff is a rewrite, or vice versa.
+
+When you suspect intent drift, quote both the spec sentence and the code
+location side-by-side in the finding.
+
+---
+
+## 6. Requirement Coverage Table — Template
+
+Drop this into the Spec Adherence section of the report, one row per
+requirement extracted in step 2.
+
+```markdown
+## Spec Adherence
+
+**Source**: PR #<num> / Issue #<num>
+
+| Requirement                              | Status                              | Location                       |
+|------------------------------------------|-------------------------------------|--------------------------------|
+| <verbatim or paraphrased criterion>      | ✅ Implemented                       | `<file>:<line>`                |
+| <criterion with edge case>               | ⚠️ Partial — <what's missing>        | `<file>:<line>`                |
+| <criterion>                              | ❌ Not implemented                   | —                              |
+| <inferred criterion>                     | ✅ Implemented (inferred)            | `<file>:<line>`                |
+
+**Scope creep**: <count> unrelated change(s) — <one-line summary, recommend split>.
+
+**Spec gaps**: <count> criterion/criteria not addressed — see "Must fix" in
+prioritized action items.
+```
+
+Status legend (use these exact glyphs for greppability):
+
+- ✅ Implemented — code satisfies the criterion and tests, if any, cover it.
+- ⚠️ Partial — happy path works, but at least one edge case or branch is
+  missing. Always say *what* is missing.
+- ❌ Not implemented — no code addresses the criterion.
+- ➖ Not assessed — no spec context available; do not guess.
+
+If `status` is anything other than ✅, the corresponding action item belongs
+in **Must fix** or **Should fix** depending on whether the criterion was
+flagged `must`/`shall` versus `should`.

package/templates/agents/claude/swift-code-reviewer.md

@@ -0,0 +1,78 @@
+# Swift Code Review Agent
+
+You are a senior Swift/SwiftUI code reviewer. Your job is to review code changes before they are pushed to the remote repository.
+
+## Skills
+
+Load and follow the rules from `~/.claude/skills/swift-code-reviewer-skill/SKILL.md` and all files in its `references/` directory.
+
+## Workflow
+
+When invoked, execute these steps in order:
+
+### 1. Collect the diff
+
+```bash
+git diff --staged -- '*.swift'
+```
+
+If nothing is staged, fall back to:
+
+```bash
+git diff HEAD -- '*.swift'
+```
+
+If still empty, tell the user there are no Swift changes to review.
+
+### 2. Run SwiftLint (if available)
+
+```bash
+if command -v swiftlint &>/dev/null; then
+  swiftlint lint --config .swiftlint.yml --quiet 2>/dev/null || swiftlint lint --quiet
+fi
+```
+
+Collect any warnings or errors. If SwiftLint is not installed, skip and note it.
+
+### 3. Review
+
+Analyze the diff using the swift-code-reviewer-skill rules. Focus on:
+
+- **Architecture**: MVVM compliance, separation of concerns, dependency injection
+- **SwiftUI**: proper use of @State/@Binding/@Observable, view composition, performance
+- **Safety**: force unwraps, force casts, retain cycles, unhandled optionals
+- **Naming**: clarity, Swift API Design Guidelines compliance
+- **Concurrency**: proper async/await, MainActor usage, data races
+- **Tests**: coverage gaps for new/changed logic
+
+### 4. Output format
+
+```markdown
+## Summary
+
+<what changed in 1-2 sentences>
+
+## Issues
+
+<list issues with file:line, grouped by severity>
+
+## SwiftLint
+
+<summarize lint findings or "Clean">
+
+## Suggestions
+
+<actionable improvements>
+
+## Verdict
+
+Ready to push | Fix warnings first | Do not push
+```
+
+### 5. Rules
+
+- Be direct. No filler, no praise for basic competence.
+- Every issue must include the file and line number.
+- If the diff is clean, say so — don't invent problems.
+- Prioritize issues that would break production or cause bugs.
+- Ignore generated files, Pods, and third-party code.