@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/skills/shared/external/architecture/SKILL.md

@@ -1,58 +1,125 @@
 ---
 name: architecture
-description: "Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design."
-risk: safe
-source: community
-date_added: "2026-02-27"
+description: "Stack-neutral architecture decisions: quality drivers, options with a trade-off matrix, reversibility, ADRs, fitness checks. Use when making or reviewing a significant design decision or writing an ADR."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# Architecture Decision Framework
+# Architecture Decisions
 
-> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."
+An architecture decision is any choice that is expensive to undo once other
+code depends on it. This skill is the procedure for making one deliberately and
+leaving a record a later reader can argue with.
 
-## 📑 Topics
+It is stack-neutral. For app-level patterns on a specific platform, load
+`swift-architecture` (MV, MVVM, TCA and friends on Apple platforms) or
+`android-architecture` (layered modules with Hilt). For line-level readability
+use `clean-code`. For a contested call that needs several independent opinions,
+`council` runs that debate; this skill supplies the frame it argues inside.
 
-| Topic | Covers | When it applies |
-|------|-------------|--------------|
-| Context discovery | Questions to ask, project classification | Starting architecture design |
-| Trade-off analysis | ADR templates, trade-off framework | Documenting decisions |
-| Pattern selection | Decision trees, anti-patterns | Choosing patterns |
-| Worked examples | MVP, SaaS, Enterprise examples | Reference implementations |
-| Patterns reference | Quick lookup for patterns | Pattern comparison |
+## When a decision deserves this process
 
----
+Run the full procedure when at least one is true:
 
-## 🔗 Related Skills
+- Undoing it later would touch more than one team, service or release.
+- It fixes a data format, a public contract or a storage engine.
+- Two competent people on the team already disagree about it.
+- It trades one quality attribute against another (for example latency for
+  consistency).
 
-| Skill | Use For |
-|-------|---------|
-| `@[skills/database-design]` | Database schema design |
-| `@[skills/api-patterns]` | API design patterns |
-| `@[skills/deployment-procedures]` | Deployment architecture |
+A choice that one engineer can reverse in an afternoon does not need an ADR.
+Make it, note it in the pull request, move on.
 
----
+## Step 1: Write the forces down
 
-## Core Principle
+Before any option is named, list what the design has to satisfy. Options chosen
+before the forces are written tend to be justified backwards.
 
-**"Simplicity is the ultimate sophistication."**
+**Functional scope.** One or two sentences: what must the system do that it does
+not do today.
 
-- Start simple
-- Add complexity ONLY when proven necessary
-- You can always add patterns later
-- Removing complexity is MUCH harder than adding it
+**Quality drivers.** Pick the three to five that actually bind, and make each
+one measurable. "Fast" is not a driver; "p95 order lookup under 200 ms at 500
+requests per second" is.
 
----
+| Attribute | Typical measurable form |
+|-----------|-------------------------|
+| Performance | p95/p99 latency at a stated load |
+| Availability | allowed downtime per month, recovery time objective |
+| Consistency | which reads may be stale, and for how long |
+| Scalability | growth factor the design must absorb without rework |
+| Security | data classes handled, trust boundaries crossed |
+| Operability | who is paged, what they can see, how they roll back |
+| Changeability | which parts are expected to change often |
+| Cost | monthly run cost ceiling, build effort ceiling |
+
+**Constraints.** Things that are not up for debate: an existing platform, a
+compliance rule, a deadline, the skills the team has today. Write them as
+constraints so nobody spends an hour optimising them away.
+
+**Assumptions.** What you believe but have not checked (traffic shape, data
+volume, number of clients). Each one is a risk; mark the ones that would flip the
+decision if they turned out wrong.
+
+## Step 2: Generate real options
+
+Aim for three options, and make sure they differ in kind, not only in brand.
+"Postgres versus MySQL" is one option with two vendors; "relational store versus
+event log with projections versus keep the current document store and add an
+index" is three.
+
+Always include:
+
+- **Do the least.** Extend what exists. It is often right, and it is the
+  baseline every other option must beat.
+- **The option someone is excited about.** Give it a fair hearing in writing
+  instead of a hallway argument.
+- **One option that optimises a different driver** than the favourite does.
+
+Sketch each option at the level of boxes and arrows: components, who owns the
+data, how requests and failures flow. If an option cannot be sketched, it is not
+yet an option.
+
+## Step 3: Compare in a trade-off matrix
+
+Score each option against each driver from Step 1. Use a small scale (for
+example minus, zero, plus) and a sentence of evidence per cell; the evidence is
+the valuable part, the score is a summary.
+
+Example for a notes service that must add full-text search:
+
+| Driver | A: DB full-text index | B: Dedicated search engine | C: Client-side search |
+|--------|----------------------|----------------------------|-----------------------|
+| p95 search under 300 ms on 5M notes | 0 - fine to ~10M rows per benchmark on staging | + - built for it | - - only works for small accounts |
+| Operability | + - no new system | - - new cluster, new on-call runbook | + - nothing server-side |
+| Consistency with writes | + - same transaction | 0 - seconds of lag via change feed | + - local |
+| Build effort | + - days | - - weeks, plus sync pipeline | 0 - moderate, per client |
+
+Read the matrix for two things:
+
+1. **Dominated options.** If one option is no better than another on any driver,
+   drop it and say why.
+2. **The deciding driver.** Usually one row decides. Name it explicitly in the
+   ADR; it is what a future reader needs to re-open the decision when that
+   driver changes.
+
+## Step 4: Judge reversibility
+
+For each surviving option ask: if this turns out wrong in a year, what does
+backing out cost?
 
-## Validation Checklist
+- **Two-way door.** Behind an interface, data easily migrated, few callers.
+  Decide quickly, bias to the simplest option.
+- **One-way door.** Public contracts, persisted formats, vendor lock-in, team
+  boundaries. Slow down, prototype the riskiest assumption, get a second review.
 
-Before finalizing architecture:
+You can often turn a one-way door into a two-way one cheaply: put an interface
+in front of the new component, dual-write for a period, version the contract
+from day one, keep the old path behind a flag. Note such mitigations as part of
+the option, because they change its cost.
 
-- [ ] Requirements clearly understood
-- [ ] Constraints identified
-- [ ] Each decision has trade-off analysis
-- [ ] Simpler alternatives considered
-- [ ] ADRs written for significant decisions
-- [ ] Team expertise matches chosen patterns
+## Details on demand
 
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+Load `references/adr-and-review.md` for step 5 (the ADR template), step 6 (fitness checks), questions for reviewing a design, and common failure shapes.

package/pipeline/skills/shared/external/architecture/references/adr-and-review.md

@@ -0,0 +1,76 @@
+# ADRs, fitness checks and design review
+
+Companion to `../SKILL.md` for the `architecture` skill.
+
+## Step 5: Record it as an ADR
+
+Store ADRs next to the code (`docs/adr/NNNN-short-title.md`), numbered, never
+rewritten. A reversed decision gets a new ADR that supersedes the old one.
+
+```markdown
+# NNNN. Short imperative title
+
+Status: proposed | accepted | superseded by NNNN
+Date: YYYY-MM-DD
+Deciders: names or roles
+
+## Situation
+What changed, and the forces from Step 1 that bind (drivers with numbers,
+constraints, risky assumptions).
+
+## Options considered
+One paragraph per option, including "do the least".
+
+## Decision
+The chosen option in one sentence, then the deciding driver.
+
+## Consequences
+What becomes easier, what becomes harder, what new work this creates,
+and which assumption would make us revisit it.
+
+## Checks
+How we will know the decision still holds (see fitness checks).
+```
+
+Keep an ADR short enough to read in five minutes. Link to benchmarks and
+spikes rather than pasting them.
+
+## Step 6: Add fitness checks
+
+A decision that nothing enforces decays. For each deciding driver, add an
+automated or scheduled check that fails when the decision stops being true:
+
+- **Dependency rules.** A test or lint rule that fails when the `orders` module
+  imports from `billing` internals, or when a layer skips another.
+- **Performance budgets.** A load test in CI or a production SLO alert tied to
+  the latency number in the ADR.
+- **Contract tests.** Consumer-driven tests that pin the public API shape.
+- **Cost alerts.** A budget alarm at the ceiling the ADR assumed.
+- **Review date.** For decisions resting on an unverified assumption, a dated
+  reminder to check it.
+
+## Reviewing someone else's design
+
+Work through the same steps in order and ask for whatever is missing:
+
+1. Are the drivers measurable, and are there five or fewer?
+2. Was "do the least" considered and beaten on evidence?
+3. Does each claim in the comparison cite a measurement, a spike or a documented
+   limit, or is it opinion?
+4. Is the one-way-door part identified, and is there a mitigation?
+5. What fails first under ten times the load, and who notices?
+6. What is the rollback plan on day one?
+
+## Common failure shapes
+
+- **Resume-driven design.** The option is interesting rather than needed. The
+  "do the least" row usually exposes it.
+- **Premature distribution.** Splitting into services before the module
+  boundaries are proven inside one deployable. Prove the seam in-process first.
+- **Hidden shared database.** Two services that write the same tables are one
+  service with two deploy pipelines.
+- **Undocumented driver.** The decision was right, but nobody wrote down why, so
+  the next team reverses it when the context is gone.
+- **Architecture by accretion.** No single decision was wrong, but nobody ever
+  recorded the cumulative shape. A periodic diagram-plus-ADR-index review
+  catches this.

package/pipeline/skills/shared/external/authentication/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: authentication
 description: "Implement iOS authentication flows with AuthenticationServices and LocalAuthentication. Use when building Sign in with Apple, passkey/WebAuthn registration or sign-in with ASAuthorizationPlatformPublicKeyCredentialProvider, ASAuthorizationController credential state and revocation handling, ASWebAuthenticationSession OAuth or third-party login, Password AutoFill, identity-token server validation, or local biometric re-authentication with LAContext."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # Authentication

package/pipeline/skills/shared/external/avkit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: avkit
 description: "Create media playback experiences using AVKit. Use when adding video players with AVPlayerViewController, enabling Picture-in-Picture, routing media with AirPlay, using SwiftUI VideoPlayer views, configuring transport controls, displaying subtitles and closed captions, or integrating AVFoundation playback with system UI."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # AVKit

package/pipeline/skills/shared/external/background-processing/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: background-processing
 description: "Schedule and execute background work on iOS using BGTaskScheduler. Use when registering BGAppRefreshTask for short background fetches, BGProcessingTask for long-running maintenance, BGContinuedProcessingTask (iOS 26+) for foreground-started work that continues in background, background URLSession downloads, or background push notifications. Covers Info.plist configuration, expiration handling, task completion, and debugging with simulated launches."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
-
 # Background Processing
 
 Register, schedule, and execute background work on iOS using the BackgroundTasks

package/pipeline/skills/shared/external/backlog/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: backlog
-version: 1.0.0
-description: "The engineering backlog registry for deferred-but-approved work in this codebase. Every job the user defers ('defer it', 'add it to the list', 'later', 'not now') lands HERE with its full spec, origin, and unblock condition, so deferral never means loss. Load when the user defers work, asks 'what's on the backlog / the list', says 'work the backlog' / 'pick up <item>', or when completing an item. The bundled BACKLOG.md is the registry; entries move deferred -> ready -> in-progress -> done, and the registry is re-audited against live code - a rotted entry deletes, a done record retires once what it taught is re-homed in the skill that owns it. This records WHAT IS OWED; git history records what happened."
+description: "The engineering backlog registry for deferred-but-approved work: each deferred job lands here with its spec, origin and unblock condition. Use when the user says 'defer it', 'add it to the list', 'later' or 'not now', asks what is on the backlog, says 'pick up {id}', or completes an item. BACKLOG.md is the registry; entries move deferred, ready, in-progress, done, and a re-audit deletes rotted ones."
 user-invocable: true
 argument-hint: [list | add | pick <id> | done <id> | re-audit]
 allowed-tools: Read, Grep, Glob, Edit, Write
+metadata:
+  version: 1.0.0
 ---
 
 # backlog - deferred work, kept whole

package/pipeline/skills/shared/external/callkit-voip/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: callkit-voip
 description: "Implement VoIP calling with CallKit and PushKit. Use when building incoming/outgoing call flows, registering for VoIP push notifications, configuring CXProvider and CXCallController, handling call actions, coordinating audio sessions, or creating Call Directory extensions for caller ID and call blocking."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # CallKit

package/pipeline/skills/shared/external/callkit-voip/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill_name": "callkit",
+  "skill_name": "callkit-voip",
   "evals": [
     {
       "id": 0,

package/pipeline/skills/shared/external/ci-cd-pipelines/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: ci-cd-pipelines
 description: "CI/CD pipelines: GitHub Actions workflows, Docker multi-stage builds, environment management, secret management, deployment strategies. Use when setting up or fixing a build, test or deploy pipeline."
-tags: [ci-cd, github-actions, docker, deployment, devops, backend]
-version: "2025.1"
+metadata:
+  tags: [ci-cd, github-actions, docker, deployment, devops, backend]
+  version: "2025.1"
 ---
 
 # CI/CD Pipelines

package/pipeline/skills/shared/external/clean-code/SKILL.md

@@ -1,94 +1,196 @@
 ---
 name: clean-code
-description: "This skill embodies the principles of \"Clean Code\" by Robert C. Martin (Uncle Bob). Use it to transform \"code that works\" into \"code that is clean.\""
-risk: safe
-source: "ClawForge (https://github.com/jackjin1997/ClawForge)"
-date_added: "2026-02-27"
+description: "Readability checks for code in any language: names, function focus, control flow, side effects, errors, comments, duplication. Use when writing, refactoring or reviewing code for quality and naming."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-24"
 ---
 
-# Clean Code Skill
-
-This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean."
-
-## 🧠 Core Philosophy
-> "Code is clean if it can be read, and enhanced by a developer other than its original author."  -  Grady Booch
-
-## When to Use
-Use this skill when:
-- **Writing new code**: To ensure high quality from the start.
-- **Reviewing Pull Requests**: To provide constructive, principle-based feedback.
-- **Refactoring legacy code**: To identify and remove code smells.
-- **Improving team standards**: To align on industry-standard best practices.
-
-## 1. Meaningful Names
-- **Use Intention-Revealing Names**: `elapsedTimeInDays` instead of `d`.
-- **Avoid Disinformation**: Don't use `accountList` if it's actually a `Map`.
-- **Make Meaningful Distinctions**: Avoid `ProductData` vs `ProductInfo`.
-- **Use Pronounceable/Searchable Names**: Avoid `genymdhms`.
-- **Class Names**: Use nouns (`Customer`, `WikiPage`). Avoid `Manager`, `Data`.
-- **Method Names**: Use verbs (`postPayment`, `deletePage`).
-
-## 2. Functions
-- **Small!**: Functions should be shorter than you think.
-- **Do One Thing**: A function should do only one thing, and do it well.
-- **One Level of Abstraction**: Don't mix high-level business logic with low-level details (like regex).
-- **Descriptive Names**: `isPasswordValid` is better than `check`.
-- **Arguments**: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification.
-- **No Side Effects**: Functions shouldn't secretly change global state.
-
-## 3. Comments
-- **Don't Comment Bad Code - Rewrite It**: Most comments are a sign of failure to express ourselves in code.
-- **Explain Yourself in Code**: 
-  ```python
-  # Check if employee is eligible for full benefits
-  if employee.flags & HOURLY and employee.age > 65:
-  ```
-  vs
-  ```python
-  if employee.isEligibleForFullBenefits():
-  ```
-- **Good Comments**: Legal, Informative (regex intent), Clarification (external libraries), TODOs.
-- **Bad Comments**: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers.
-
-## 4. Formatting
-- **The Newspaper Metaphor**: High-level concepts at the top, details at the bottom.
-- **Vertical Density**: Related lines should be close to each other.
-- **Distance**: Variables should be declared near their usage.
-- **Indentation**: Essential for structural readability.
-
-## 5. Objects and Data Structures
-- **Data Abstraction**: Hide the implementation behind interfaces.
-- **The Law of Demeter**: A module should not know about the innards of the objects it manipulates. Avoid `a.getB().getC().doSomething()`.
-- **Data Transfer Objects (DTO)**: Classes with public variables and no functions.
-
-## 6. Error Handling
-- **Use Exceptions instead of Return Codes**: Keeps logic clean.
-- **Write Try-Catch-Finally First**: Defines the scope of the operation.
-- **Don't Return Null**: It forces the caller to check for null every time.
-- **Don't Pass Null**: Leads to `NullPointerException`.
-
-## 7. Unit Tests
-- **The Three Laws of TDD**:
-  1. Don't write production code until you have a failing unit test.
-  2. Don't write more of a unit test than is sufficient to fail.
-  3. Don't write more production code than is sufficient to pass the failing test.
-- **F.I.R.S.T. Principles**: Fast, Independent, Repeatable, Self-Validating, Timely.
-
-## 8. Classes
-- **Small!**: Classes should have a single responsibility (SRP).
-- **The Stepdown Rule**: We want the code to read like a top-down narrative.
-
-## 9. Smells and Heuristics
-- **Rigidity**: Hard to change.
-- **Fragility**: Breaks in many places.
-- **Immobility**: Hard to reuse.
-- **Viscosity**: Hard to do the right thing.
-- **Needless Complexity/Repetition**.
-
-## 🛠️ Implementation Checklist
-- [ ] Is this function smaller than 20 lines?
-- [ ] Does this function do exactly one thing?
-- [ ] Are all names searchable and intention-revealing?
-- [ ] Have I avoided comments by making the code clearer?
-- [ ] Am I passing too many arguments?
-- [ ] Is there a failing test for this change?
+# Clean Code
+
+Code is read far more often than it is written, and every later change starts
+with someone working out what the current code does. This skill is a set of
+questions to ask of a piece of code, in the order that finds the expensive
+problems first, plus the move that fixes each one.
+
+The repository's own conventions win. A linter rule, a module guide or a coding
+standard registry that says otherwise overrides anything here; this skill fills
+the gaps they leave.
+
+## Order of questions
+
+Work from the outside in. A clear name on a muddled body is cheaper to fix than
+a tidy body behind a misleading name, because callers only ever see the name.
+
+1. Does each name tell a caller what they get, without opening the body?
+2. Does each unit do one job at one level of detail?
+3. Can the control flow be followed top to bottom without holding state in mind?
+4. Is every change to state visible at the call site?
+5. Does every failure reach someone who can act on it?
+6. Does each comment say something the code cannot?
+7. Is each rule written down in exactly one place?
+8. Would a test fail if the behaviour broke?
+
+## 1. Names
+
+- Name by role in this domain, not by type or storage: `overdueInvoices`, not
+  `invoiceList` or `data2`.
+- A boolean reads as a claim: `isExpired`, `hasShippingAddress`, `canRetry`.
+- A function that returns something is named for what it returns
+  (`remainingBalance()`); one that acts is named for the action (`cancelOrder()`).
+- Units belong in the name when the type does not carry them: `timeoutSeconds`,
+  `distanceKm`.
+- One word per concept across the codebase. If `fetch`, `load` and `get` all mean
+  "read from the network", pick one.
+- Length follows scope: `i` is fine in a three-line loop; a module-level value
+  needs a full phrase.
+
+```python
+# Before
+def calc(d, f):
+    return d * (1 - f)
+
+# After
+def discounted_price(list_price: Decimal, discount_rate: Decimal) -> Decimal:
+    return list_price * (1 - discount_rate)
+```
+
+## 2. Units of work
+
+- One job per function. The test: describe it in one sentence without "and" or
+  "then". If you cannot, split at the conjunction.
+- One level of detail per function. A function that validates an order should
+  not also format a currency string; call a function that does.
+- Few parameters. Three or more, or any boolean flag that switches behaviour,
+  usually means a missing type or two functions sharing a name.
+- A body longer than a screen is a prompt to look for the seams, not a rule.
+
+```swift
+// Before: the flag hides two behaviours
+func export(_ report: Report, asPDF: Bool) -> Data
+
+// After: two names, no flag
+func exportPDF(_ report: Report) -> Data
+func exportCSV(_ report: Report) -> Data
+```
+
+## 3. Control flow
+
+- Handle the exits first. Guard clauses at the top keep the main path at one
+  indentation level.
+- Replace a chain of `if`/`else if` on the same value with a `switch`/`match`
+  that the compiler can check for completeness.
+- Name a compound condition: `let isEligible = age >= 18 && hasConsent` reads
+  better than the raw expression inside an `if`.
+- Nesting past two levels almost always hides a function waiting to be extracted.
+
+```typescript
+// Before
+function shippingCost(order: Order): number {
+  if (order.items.length > 0) {
+    if (!order.isDigital) {
+      return order.weightKg * RATE_PER_KG;
+    }
+  }
+  return 0;
+}
+
+// After
+function shippingCost(order: Order): number {
+  if (order.items.length === 0 || order.isDigital) return 0;
+  return order.weightKg * RATE_PER_KG;
+}
+```
+
+## 4. State and side effects
+
+- A function either answers a question or changes something. When one does both,
+  a caller who only wanted the answer triggers the change.
+- Pass what a function needs; do not let it reach into globals, singletons or
+  the clock. Inject the dependency so a test can replace it.
+- Prefer values that cannot change once built. Mutation belongs in a small,
+  named place.
+- Keep a variable's scope as small as its use.
+
+## 5. Errors and edge values
+
+- Fail where the problem is detected, with a message that names the input and
+  the expectation.
+- Do not swallow an error to keep going. Catch it only where something useful
+  can be done: retry, fall back, or report to the user.
+- Represent "no value" in the type (`Optional`, `Result`, a sealed type) instead
+  of returning a sentinel such as `-1`, an empty string or `null` by convention.
+- Check the boundaries every time: empty input, one element, the maximum, and
+  values that are present but invalid.
+
+```kotlin
+// Before: the caller cannot tell "not found" from "zero"
+fun itemCount(orderId: String): Int = repository.find(orderId)?.items ?: 0
+
+// After
+fun itemCount(orderId: String): Int? = repository.find(orderId)?.items
+```
+
+## 6. Comments
+
+- Write down why, never what. The code already says what it does; a comment that
+  repeats it goes stale the first time the code changes.
+- A comment that explains a confusing block is a request to rename or extract
+  until the comment is unnecessary.
+- Keep: the reason behind a non-obvious choice, a link to the spec or bug a
+  workaround exists for, the legal header a file must carry, and public API docs.
+- Delete: commented-out code (version control keeps it), change logs inside the
+  file, and section banners that restate the structure.
+
+## 7. Duplication and abstraction
+
+- A business rule written in two places will eventually disagree with itself.
+  Give it one home and call it.
+- Two blocks that look alike but change for different reasons are not
+  duplication; merging them couples unrelated features.
+- Wait for the third occurrence before extracting a general helper, unless the
+  repeated thing is a rule rather than a shape.
+- An abstraction earns its place when it removes decisions from callers. One that
+  only forwards arguments adds a hop and a name to learn.
+
+## 8. Tests as the specification
+
+- Each test states one behaviour in its name: `refundIsRejectedAfterShipment`.
+- Arrange, act, assert, with the act step a single call.
+- A test that cannot fail when the behaviour breaks is worse than none, because
+  it reports coverage that does not exist.
+- Fast, isolated and repeatable: no network, no shared state between tests, no
+  dependence on the clock or execution order.
+
+## Problem to move
+
+| Problem you see | Move |
+|---|---|
+| A name needs a comment to explain it | Rename |
+| A block has a comment heading it | Extract a function named after the comment |
+| A boolean parameter | Split into two functions, or pass an enum |
+| Three or more related parameters | Introduce a parameter type |
+| Deep nesting | Guard clauses, then extract the inner block |
+| A `switch` on type repeated in several places | Move the behaviour onto the types |
+| A literal with meaning (`86400`, `0.2`) | Named constant or configuration |
+| The same rule in two places | Extract once, call from both |
+| A function that reads and writes | Separate the query from the command |
+| A hard-coded dependency | Inject it |
+
+Refactor in small steps with the tests green between each, and keep a
+behaviour change out of a refactoring commit.
+
+## Reporting in a review
+
+For each finding give the location, what the problem is, why it costs the next
+reader or maintainer, and the concrete change. Rank by cost: a misleading name
+or a swallowed error outranks a long function, which outranks a style nit.
+Leave formatting to the formatter and say nothing about it.
+
+## Out of scope
+
+- Security weaknesses: use `security-review`.
+- Speed and memory: profile first, then use the stack's performance skill.
+- Module boundaries and system design: use `architecture`.
+- Language style rules a linter enforces: follow the linter.

package/pipeline/skills/shared/external/cloudkit-sync/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: cloudkit-sync
 description: "Implement, review, or improve CloudKit and iCloud sync in iOS/macOS apps. Use when working with CKContainer, CKRecord, CKQuery, CKSubscription, CKSyncEngine, CKShare, NSUbiquitousKeyValueStore, or iCloud Drive file coordination; when syncing SwiftData models via ModelConfiguration with cloudKitDatabase; when handling CKError codes for conflict resolution, network failures, or quota limits; or when checking iCloud account status before performing sync operations."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
-
 # CloudKit
 
 Sync data across devices using CloudKit, iCloud key-value storage, and iCloud

package/pipeline/skills/shared/external/cloudkit-sync/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill_name": "cloudkit",
+  "skill_name": "cloudkit-sync",
   "evals": [
     {
       "id": 1,