The trigger was a screenshot of Hello Weather: an hourly strip showing a row of 20-25% precipitation-probability labels, and no “precip later” pill anywhere on screen. The labels were advertising rain that the pill refused to mention. Two UI elements, same forecast, same screen, disagreeing about whether it was going to rain.
That’s not a bug in either element. Each one was correctly implementing its own answer to the question “is this probability worth showing?” The bug was that the codebase had four answers:
(The specific numbers - a 5% rounding step, a 20% floor - are ours and are illustrative. Nothing below depends on them; the pattern is what transfers.)
None of these were written carelessly. Each divergence had a local justification at the time it was introduced: the pill’s higher floor came from a deliberate decision to stop advertising marginal rain; the detail card’s band predated the rounding helper; the push gate was written against the value it had in hand. That’s the point worth internalizing: when the same product question is answered in multiple places, the answers don’t diverge because someone was sloppy. They diverge because each site evolves under local pressure, and nothing ties them together. This family of duplicated thresholds had already shipped at least two real bugs before the screenshot - a raw-vs-rounded mismatch on the suppression window, and a pill that stopped suppressing over rendered bars after one floor moved and the other didn’t.
The fix is not “align the constants.” Aligning the constants leaves four call sites that can drift again the day any one of them changes. The fix is making the question answerable in exactly one place:
enum PrecipDisplay {
static func showPrecip(val: Float) -> Bool {
val.toRoundedPrecip >= 0.2
}
}
extension BinaryFloatingPoint {
var toRoundedPrecip: Self {
self.rounded(to: 0.05)
}
}
That’s the entire mechanism: a pure function in a shared extensions file, compiled into all four targets (app, watch, widgets, push service). Every display gate - hourly and daily labels, bar colors, the pill’s trigger and its headline scan, VoiceOver’s per-hour precipitation clause, push copy, the stat cards’ on/off states and icons, the detail charts’ point icons, and both lock-screen slots - routes through it. Forty-four call sites.
Two design choices in that tiny function do most of the work:
All call sites pass raw values; the chokepoint rounds internally. This kills the raw-vs-rounded bug class outright, because no caller gets to choose which representation to compare. The rounding is idempotent - toRoundedPrecip of an already-rounded value is itself - so it doesn’t matter whether a caller’s value has been through the display formatter already. That property is not assumed; it’s test-pinned:
@Test func agreesForRawAndPreRoundedInputs() {
for raw in stride(from: Float(0), through: 1, by: 0.001) {
#expect(PrecipDisplay.showPrecip(val: raw) ==
PrecipDisplay.showPrecip(val: raw.toRoundedPrecip))
}
}
Alongside it, boundary tests pin the exact rounding cliff (0.174 hides, 0.175 shows). The sweep test is the important one, though: it’s the executable statement of the invariant that makes “pass whatever you have” safe.
The threshold is a member of a named type, not a constant. PrecipDisplay is an enum with no cases - it exists purely as a namespace. That sounds like ceremony until you read the standing rule that shipped with it:
Any future second threshold must land as a named
PrecipDisplaymember, never an inline constant at a call site.
This is the part that keeps the unification unified. The original divergence didn’t start as four thresholds; it started as one threshold and then a perfectly reasonable inline 0.3 at one call site. The rule doesn’t forbid a second threshold - product reality may well demand one - it forbids an anonymous one. A named member sits next to its sibling, gets reviewed as a deliberate fork of the question, and is findable by anyone auditing the family. An inline constant at a call site is invisible until it ships a screenshot.
A rule that lives only in a commit message is a rule that lasts until the commit scrolls off the first page of git log. This one landed in the code-review skill - the checklist the review agent walks on every PR - as two rewritten bullets. Sanitized but structurally intact:
Precip display gates (hourly/daily labels and bar colors, the precip-later button, VoiceOver per-hour precip clauses, push-copy precip lines, stat card/detail on-off states and icons) route through
PrecipDisplay.showPrecip- new or modified display gates must call it, never hardcode a literal. Deliberate exceptions (relevance thresholds, the chart-summary> 0accessibility gates, the frozen style catalogs) are inventoried in the unification plan.The precip-later button must never cover a rendered bar. Since the unification, bars, labels, and the button share one floor, so “first qualifying index ≥ visible-column threshold” alone guarantees no rendered bar sits under it - there is deliberately no separate suppression clause. If a second floor ever returns, it must land as a named
PrecipDisplaymember, and the explicit suppression clause - rounded on BOTH sides; the raw/rounded split shipped a bug once - becomes load-bearing again.
The second bullet is doing something we’ve come to think of as essential to any simplification: it records what becomes load-bearing again if the simplification is ever reversed. With one predicate, the pill’s old on-screen suppression clause is provably redundant - “the first qualifying hour is past the visible window” and “no rendered bar in the visible window” are the same statement when bars and pill share a predicate - so it was deleted, with the proof sketched in the PR. But that equivalence only holds while there’s one floor. The checklist doesn’t just say “we deleted X”; it says “X returns, in this exact form, with rounding on both sides, the day the floors fork.” Deleting code is easy. Deleting code while leaving behind an accurate map of the conditions under which it must come back is the version that doesn’t cost your successors a shipped bug.
The same discipline applied to a decision that got superseded along the way. The designer had proposed a two-threshold model for the pill - display gates forgiving, the attention-grabbing pill stricter, so it only fires on evidence worth interrupting for. The shipped change went uniform instead: simplest rule first, tweak with field evidence in hand. But the designer’s variant wasn’t discarded - it’s preserved in the plan doc as the ready alternative, pre-built on a branch, with explicit instructions that reinstating it means a named member and the restored suppression clause. Neither side had field evidence, so the plan records the two options as equal-footing, not default-vs-exception. Superseding a design verdict without recording it is how the same debate gets re-litigated from scratch in six months.
Here’s the part that makes threshold unification more than hygiene. Sweeping every comparison site into one function forces you to actually read every comparison site - and one of them didn’t parse.
The lock-screen rectangular widget and the matching watch complication have a designed slot: on rainy hours, the precip percentage replaces the temperature. Nice touch. The gate for it compared the probability - a 0-to-1 fraction - against an integer percent:
// before: probability is 0.0-1.0; the gate wants "20"
if hour.precipProbability >= 20 { ... }
A fraction is never ≥ 20. The gate was always false. The slot had never rendered, for anyone, since the day it shipped - and nobody noticed, because “the gate is always false” is visually indistinguishable from “it hasn’t rained lately.” A units mismatch with a plausible-looking failure mode is the quietest bug there is. Routing the site through the chokepoint fixed it as a side effect - the chokepoint takes fractions, full stop - and the feature rendered for the first time. (Which produced its own rider: localized percent strings like “100 %” overflow a 31-point slot, hence a minimumScaleFactor on the label. Features that have never rendered have also never been through layout QA.)
This is the strongest practical argument for the chokepoint pattern: a function with one signature is also a units contract. Four scattered comparisons can each pick their own units and be wrong independently. Forty-four call sites feeding one Float-taking function cannot.
An exercise like this fails in two directions: leaving divergent sites out, and sweeping in sites that only look like the same question. The second failure is subtler. Not every fractional comparison against a probability is a display gate:
> 0, deliberately broader than the display floor: a VoiceOver description of a whole chart (“up to N percent”) should describe data the chart plots, and the detail charts plot sub-threshold values.The important move isn’t excluding them - it’s that the exclusions are inventoried, in the plan doc the checklist bullet points at, each with the reason it’s a different question. An undocumented exemption is indistinguishable from a site the sweep missed. A documented one is a decision.
“We routed everything through one function” is a claim, and claims from the session that did the routing are worth exactly as much as any other self-review - which is to say, they inherit every blind spot of the authoring context. So before merge, the change went through the adversarial review process: four independent, read-only reviewers, none with the session’s reasoning.
The one worth singling out here was an exhaustive-sweep reviewer whose brief was not “review this diff” but “prove or refute the completeness claim”: find every fractional probability comparison in the codebase and account for it. Its report: outside the frozen style catalog, exactly four such comparisons exist - the chokepoint, plus the three documented relevance-scoring exemptions. Not “the diff looks complete.” An enumeration, checked against the inventory, with zero unaccounted-for sites.
That’s a materially different kind of assurance, and it’s cheap to ask for. A unification PR’s central claim is universally quantified - no other site answers this question - and a diff review can’t verify a universal claim because the sites that falsify it are, by definition, not in the diff. Give one reviewer the whole codebase and the quantifier as its brief.
The other lenses earned their keep too: a behavioral pass traced boundary values through every surface and confirmed the suppression-clause deletion with predicate math, and its two confirmed findings (an anchor-selection gap in the pill’s headline scan, and an off-by-one where the “starting soon” copy announced the precip type of the hour after the match - “rain possible in 3h” for what was actually snow) were fixed before merge. Known geometry caveats - wide-layout column counts on tablets and landscape phones are hand-maintained estimates rather than measured - were recorded in the plans as deferred, with the measurement rework named as the real fix.
Prompt 1: “see recent work in ~/Code/helloweather, perhaps a blog post about our opus 4.8 agents and why we decided to do that? perhaps something about the swift testing + snapshots inspired by minitest-snapshots? anything else? bring me a list of potential post ideas for review.”
Prompt 2: “skip 4, 5, 6, 9 but create posts for each of the others in the 1-9 list. also add Four Answers to One Question, and Write the Rule, Not the Story – show me a concise version of your plan and then I can approve” — then “proceed, one pr per post”
Research by one Claude agent per repo mining git history since the previous post; this draft was written by a dedicated agent from that research plus the underlying commits and skill files, then reviewed before publishing.
]]>Hello Weather’s watch app has an hourly strip - 24 hour columns you drag horizontally. On hardware, the drag was choppy, and it was choppy for a reason that generalizes to almost any SwiftUI list: during a drag, the body runs every frame, and computed properties don’t know they’re in a loop.
The strip’s drag is a @GestureState driving an .offset through a computed property, so every touch event re-evaluates the whole body. Inside that body is a ForEach over 24 hours, and inside the ForEach are reads of computed properties that are invariant across the loop:
// In a shared extension - every one of these is a computed property.
extension HourlyView {
var hourlyData: [Forecast.Hour] {
viewModel.weather?.forecast?.hourly?.data ?? Forecast.Fallback.hourlyData
}
var hourly: [Forecast.Hour] {
Array(hourlyData.prefix(min(hourCount, hourlyData.count)))
}
var maxHourlyTemp: Int {
let safeCount = min(hourCount + 2, hourlyData.count)
return (hourlyData.prefix(safeCount).map { $0.temperature ?? 0 }.max() ?? 0).toInt
}
// ...minHourlyTemp and showHourlyPrecips, same shape
}
Each looks innocent alone. But hourly[index] materializes a fresh array per subscript, each hour column reads maxHourlyTemp, minHourlyTemp, and showHourlyPrecips (each a prefix-and-map over the data), and the day-boundary check between adjacent hours constructed a Calendar per comparison - 23 of them for 24 hours. Totaled up: roughly 142 array allocations and 23 Calendar constructions per body evaluation, which during a drag means per frame, on a watch.
Nobody wrote that. It’s what accretes when “add a computed var to the shared extension” is the path of least resistance for four years, and it’s invisible until a gesture makes the body hot.
letSwiftUI evaluates a computed property every time it’s read; it has no memoization. But a let at the top of a @ViewBuilder evaluates exactly once per body pass. So the fix is almost embarrassingly small - snapshot the invariants above the loop:
private var hourlyChart: some View {
let hours = hourly
let maxTemp = maxHourlyTemp
let minTemp = minHourlyTemp
let showPrecips = showHourlyPrecips
let dayCalendar = settingsManager.hourlyIsGrouped
? viewModel.weather?.forecast?.currentCalendar
: nil
return HStack(spacing: 2) {
ForEach(hours.indices, id: \.self) { index in
let hour = hours[index]
if index > 0,
let calendar = dayCalendar,
let currentTime = hour.time,
let previousTime = hours[index - 1].time,
calendar.startOfDay(for: currentTime) != calendar.startOfDay(for: previousTime) {
DaySeparatorView(day: currentTime)
}
Hour(max: maxTemp, min: minTemp, bar: hour, showPrecips: showPrecips)
}
}
}
Per body pass: one array, one max, one min, one precip scan, one calendar. Two details worth noting because they bit us:
hours = hourly), not Swift’s shadowing shorthand. let x = x works inside if let, but at declaration scope it does not compile - use a distinct name or self.x.@ObservedObject, @EnvironmentObject), not property-level - when the view model changes, the body re-runs and re-snapshots. A let inside body is always exactly as fresh as the body pass that created it.One ForEach, one afternoon. Except a three-agent audit then went looking for the same class across the app, watch, and widget targets - and found it in 51 files. Same shape everywhere: settings pickers rebuilding localized name dictionaries per option, a radar legend measuring label widths per label per animation frame, a locations list running three JSON decodes per row, stats charts re-deriving ranges per data point.
The sweep that fixed all 51 files went through two adversarial review rounds (seven independent reviewers, run per the practice in /adversarial-review-rounds/), and the reviewers’ confirmed findings turned “hoist the invariants” from an instinct into a ruleset. This is the part worth stealing, because every one of these rules exists because the naive hoist was wrong:
Hoist only what is provably invariant AND unconditionally evaluated. These are two separate tests. A sparkline view read its precip range only behind if showsCurve - hoisting that read above the guard made it run for every daily row, including rows where the server’s min...max bounds could be inverted, which traps ClosedRange at construction. The hoist widened both the performance cost and the crash surface. If the original read sat behind a condition, the hoist keeps the same condition (with placeholder values for the other branch), or it doesn’t happen.
Hoist INTO deferred builders, never out of them. Menu and Picker content closures don’t evaluate at body time - they evaluate at presentation time. A names dictionary hoisted from inside a Menu builder up to body scope changes freshness: the user now sees a snapshot from whenever the body last ran, not from when they opened the menu. Round two of review moved one of ours back inside each menu builder for exactly this reason. The flip side is free wins: work already inside a deferred builder that runs per option can be hoisted to the top of that builder, and it still only costs anything when the menu opens.
Leave onAppear and action-closure reads live. Same principle, other direction: those closures run later than body, and they should see the world as it is when they fire, not a body-time snapshot.
Pass optionals through; don’t ?? "". Several hoists turned force-unwraps and dictionary lookups into parameters. Where the receiving view’s parameter is Optional, pass the optional: nil makes SwiftUI skip the subview entirely, while "" renders an empty shell that occupies layout. They are not the same view tree, and the diff that “just adds a fallback” is a visible behavior change.
Harden server-fed ranges while you’re in there. Any min...max built from network data gets clamped (lower...max(lower, upper)), and any stride gets a > 0 step guard - review found an empirically verified stride-by-zero trap sitting next to one of the hoists.
The meta-rule: a “mechanical” perf sweep isn’t mechanical. Every one of those findings came from a reviewer with no stake in the sweep being simple.
Here’s the process half, and the more transferable lesson.
The all-at-once sweep PR was, by every formal measure, done. Build and unit-test gates green at every commit. Two adversarial review rounds survived, every finding adjudicated and fixed. Fifty-one files of consistent, pattern-applying change.
We closed it anyway.
Not because anything was wrong with it - because 51 files is beyond confident human review, and each review round had surfaced new issues, which is the strongest possible evidence that another round would too. “All checks passed” measures what the checks measure. The honest question at the merge call is “can a human vouch for this diff?”, and for 51 files of changes that are 90% mechanical and 10% judgment, the answer was no - the 10% hides in the 90%.
So the PR became a patch source instead of a merge candidate: closed, with its branch kept on origin under a stable name, and a plan doc decomposing it into 11 slices - one to four files each, ordered, with per-slice notes carrying exactly what an implementer needs. The two slices that carry deliberate behavior deltas (the range-clamping hardening, and a rewrite that stops force-unwrapping a nullable timestamp so a missing time skips a separator instead of crashing) are flagged in the table and must disclose those deltas in their PR bodies. In a sliced re-land, “mostly mechanical” is no longer an acceptable summary - each slice is either behavior-identical or it says what changed.
The extraction recipe matters more than it looks:
git diff main...fix/foreach-hoisting -- <this slice's paths>
applying the latest state of each file from the banked branch - never cherry-picking the original sweep commit alone. The review-fix commits amend the sweep, so commit one by itself contains exactly the bugs the reviewers caught. And since main drifts while slices land one at a time, each slice re-verifies its files against fresh main before applying. Each slice PR cites the banked branch and the reviews it already survived, so slice review is cheap: confirm the extraction is faithful and the slice is self-contained, not re-litigate the pattern.
The watch strip went first, promoted out of the slice sequence into its own release-blocker lane. One file, byte-identical to the banked version, verified against branch history that the review-fix commits never touched it. Its PR states the honest expectation up front: finger-tracked dragging improves markedly, but the momentum glide after release stays juddery - the deceleration loop mutates state from a Task.sleep(16ms) loop, and watchOS has no display-link to align ticks to vsync, so cheaper frames can’t fix irregular presentation. That expectation is written down before the hands-on device check by the project owner, which is the decision gate for whether a separate paged-navigation rewrite (also built, also banked) ships or closes. Writing the expected outcome down before the check is what keeps the check honest.
The widget strips went second: pure hoists in the hourly and minutely widget views, where body cost matters most because widget rendering runs in a time-constrained context. A read-only mini-review returned zero findings and one good nit - with the hoists, an empty data array now evaluates the three getters once instead of zero times, which is safe but is exactly the kind of edge a per-slice review can actually hold in its head. That nit is the sliced approach working as designed.
The same audit surfaced a Phase-2 list that the mechanical sweep deliberately excludes, because these need design rather than a let:
Calendar constructions and 72 linear scans per strip body evaluation, across every target that shares the row view. The fix is a parent-computed calendar and sun-event map passed down, which touches shared view APIs.allHoursInDay.map { first(where:) } - a linear search per hour. Needs a Date-keyed dictionary.UserDefaults(suiteName:) and Locale on every string resolution. Every “rebuild the names dictionary per row” finding in the sweep was this cost times N; caching it needs language-change invalidation and its own careful PR.That’s the payoff of auditing a bug class instead of fixing a bug: the sweep repaired the sites, but the audit found the systems. Hoisting is the floor. The ceiling is making the expensive thing cheap once, for everyone.
ForEach are the first place to look, because cost there multiplies by element count.let at the top of the builder is the cache, it’s one line, and it’s always exactly as fresh as the body pass.Prompt 1: “see recent work in ~/Code/helloweather, perhaps a blog post about our opus 4.8 agents and why we decided to do that? perhaps something about the swift testing + snapshots inspired by minitest-snapshots? anything else? bring me a list of potential post ideas for review.”
Prompt 2: “skip 4, 5, 6, 9 but create posts for each of the others in the 1-9 list. also add Four Answers to One Question, and Write the Rule, Not the Story – show me a concise version of your plan and then I can approve” — then “proceed, one pr per post”
Research by one Claude agent per repo mining git history since the previous post; this draft was written by a dedicated agent from that research plus the underlying commits and skill files, then reviewed before publishing.
]]>Snapshot testing lives or dies on authoring cost. If asserting “this output stays exactly like this” takes one line, people snapshot everything worth snapshotting. If it takes a recorder class, a file-naming decision, and a bespoke regeneration flag, people write the snapshot test for the one system that justified the ceremony and skip it everywhere else.
The Hello Weather iOS repo was living the second case. It had two snapshot-shaped systems, both good, both bespoke: a golden-table recorder that rewrites a committed Swift file with every language x date-format combination, and a diff-on-fail report comparison on a refactor branch. Each one is a whole recorder/tests pair, hand-built for a single domain. Adding a new snapshot contract - a sync payload shape, a widget timeline dump - meant building a third one.
Meanwhile the Ruby web repo has had cheap snapshots for years: a ~120-line gem (minitest-snapshots) plus house conventions, and as a direct result, about 180 committed snapshot files across 17 test suites covering things nobody would have written a bespoke recorder for.
So we designed a port. The interesting part is what the port is: not the gem, not a Swift package, not a dependency on the well-known Swift snapshot-testing library. A single ~120-line internal helper file, because everything risky was already proven in-repo and the only missing piece was the ergonomic layer.
One thing to be clear about up front: this is a design record, not a shipping report. The decision and the full design landed as a plans-only PR (iOS #1484, 2026-08-04); the implementation is deliberately queued behind an in-flight refactor program so it adds no moving parts to a release-blocker lane. The code below is the reviewed design, including the parts flagged for verification. We think the decision record is worth publishing on its own, because the decision is the reusable part.
The gem’s mechanics are simple: assert_matches_snapshot value compares against test/snapshots/<suite>/<test>__<n>.snap.yaml, auto-created on first run and auto-numbered per call within a test; rails test --update-snapshots overwrites everything; and a CI lock makes a missing snapshot a hard failure under ENV["CI"], so CI can never silently bless a new one.
Three ergonomic properties fall out of that, and they are the whole reason the tool gets used:
Everything else in the web repo is convention layered on that primitive, and two of those conventions are worth stealing independently.
The most-copied misuse of snapshot testing is freezing a raw payload - a wall of JSON that nobody can review, where every diff is noise. The web repo’s habit runs the other way: the snapshotted artifact is usually a derived, human-readable summary built specifically to be diffed.
The flagship example: each weather-data adapter’s output is snapshotted as a comparison table against a reference adapter, field by field:
+-------------------------------+----------------------+----------------------+
| | Adapter Under Test | Reference |
+-------------------------------+----------------------+----------------------+
| timezone | America/Chicago | America/Chicago |
| currently.temperature | 50.95 | 47.0 |
| currently.icon | cloudy | cloudy |
| currently.humidity | 0.5 | 0.61 |
| currently.windBearing | 120 | 90 |
A reviewer scanning that diff can see at a glance whether a parser change moved a field, dropped one, or drifted from the reference - which is a categorically different experience from diffing raw vendor JSON.
The same move shows up at other layers. SQL behavior is frozen as a normalized statement sequence - literals replaced, comments stripped - so the snapshot captures query shape and count, not volatile values:
def assert_sql(&block)
sql = []
subscriber = ->(_name, _start, _finish, _id, payload) do
sql << payload[:sql].split("/*").first.gsub(/\d+/, "?")
end
ActiveSupport::Notifications.subscribed(subscriber, "sql.active_record", &block)
assert_matches_snapshot sql.join("\n") + "\n"
end
And HTTP concurrency behavior is frozen as a spy’s serial/parallel request counts (a request counts as serial if it completed on the same fiber as the previous one), snapshotted as two-line YAML. A change that accidentally serializes a parallel fetch fails a test with a two-line diff.
In each case the code that derives the summary is the investment, and assert_matches_snapshot is the free part. That division of labor only works when the assertion is free.
Because the assertion is one line, generating tests is cheap. The source smoke suite loops over every active data source and every unit system it supports, defining a snapshot test per combination:
Api::Weather::ACTIVE_SOURCES.excluding(REFERENCE_SOURCE).each do |source|
define_method "test_compare_#{source}_to_reference" do
vcr_use_cassette("smoke_test_#{source}_us_forecast") do
table = Api::Table.new(sources: [source, REFERENCE_SOURCE])
assert_matches_snapshot table.pack.to_s
end
end
end
Api::Weather::ACTIVE_SOURCES.each do |source|
Api::Weather.source_class(source).supported_source_units.each do |units|
define_method("test_#{source}_#{units}") do
# ...build the output table for this source + units...
assert_matches_snapshot table.pack.to_s
end
end
end
Adding a new data source to the app automatically adds its comparison test, its per-unit-system output tests, and its request-count tests - the loop picks it up, the first run records the snapshots, and the review is the diff of the new files. Nobody writes tests for a new source; they review what the loop recorded.
Snapshot suites accumulate two failure modes, and the web repo has a written rule for each:
en will happily pass while every other language regresses. The repo rule: when snapshotting localized content, assert a non-English language too.The obvious move for the iOS side was to adopt the well-known Swift snapshot-testing library. We decided against it - not because there’s anything wrong with it, but because an audit of the repo showed every risky mechanic was already proven in-house, and the library’s breadth (image strategies, a trait system) is surface area the text-snapshot use case doesn’t need. It would also have been the first package ever linked into the test target, plus a new entry in the monthly dependency-update cycle. The library’s core module remains the explicit upgrade path if image or SwiftUI-view snapshots are ever wanted.
The audit is the part worth copying, because “can our simulator tests even do this?” is the question that usually pushes teams toward a dependency. Three mechanics, three existing proofs:
URL(fileURLWithPath: #filePath) and rewrites a committed Swift file in place from an app-hosted simulator test - the simulator shares the host filesystem, so #filePath from a test file is a real, writable path into the repo checkout.xcodebuild does not forward arbitrary env vars to tests; it forwards only vars prefixed TEST_RUNNER_, stripping the prefix. The repo’s bin/unit-test already plumbs the golden-record flag through exactly this mechanism.Issue.record, naming the file and the regenerate command. Lift it.With all three proven, the only thing missing was the ergonomic layer - which is ~120 lines. That’s the thesis: port the three properties that make the tool get used; don’t import a library to get mechanics you already have.
One deliberate ruling worth recording: the new surface matches the Ruby names exactly - --update-snapshots as the flag, UPDATE_SNAPSHOTS as the env var, assertMatchesSnapshot as the helper, a snapshots/ directory mirroring the web repo’s test/snapshots/. The repo’s existing env flags carry an app-specific prefix; the ruling was to not carry that legacy prefix onto new surface for consistency’s sake. When two codebases share a convention, an engineer (or an agent) moving between them should find the same words. Prefer the better name; don’t propagate churn-avoidance naming into the future.
The whole helper is one file in the test target. The core of it, as designed:
import Testing
import Foundation
enum Snapshots {
static let directory = URL(fileURLWithPath: #filePath)
.deletingLastPathComponent()
.appendingPathComponent("snapshots")
static var updating: Bool {
ProcessInfo.processInfo.environment["UPDATE_SNAPSHOTS"] == "1"
}
static var locked: Bool {
ProcessInfo.processInfo.environment["CI"] != nil
}
private static let lock = NSLock()
private static var counters: [String: Int] = [:]
static func nextIndex(forKey key: String) -> Int {
lock.lock()
defer { lock.unlock() }
let next = (counters[key] ?? 0) + 1
counters[key] = next
return next
}
static func sanitized(_ component: String) -> String {
component.lowercased()
.replacingOccurrences(of: "[^a-z0-9]+", with: "_", options: .regularExpression)
.trimmingCharacters(in: CharacterSet(charactersIn: "_"))
}
}
func assertMatchesSnapshot(
_ value: String,
named name: String? = nil,
filePath: String = #filePath,
function: String = #function,
sourceLocation: SourceLocation = #_sourceLocation
) {
let suite = Snapshots.sanitized(
URL(fileURLWithPath: filePath).deletingPathExtension().lastPathComponent)
let test = Snapshots.sanitized(function.replacingOccurrences(of: "()", with: ""))
let suffix = name.map(Snapshots.sanitized)
?? String(Snapshots.nextIndex(forKey: "\(suite)/\(test)"))
let snapshotURL = Snapshots.directory
.appendingPathComponent(suite)
.appendingPathComponent("\(test)__\(suffix).snap.txt")
if !Snapshots.updating,
let recorded = try? String(contentsOf: snapshotURL, encoding: .utf8) {
if recorded == value { return }
Issue.record(
"output drifted from the snapshot — regenerate with " +
"bin/unit-test --update-snapshots, then review every changed line. " +
"First differences:\n\(firstDifferences(recorded, value))",
sourceLocation: sourceLocation)
return
}
guard !Snapshots.locked else {
Issue.record(
"snapshot is missing or an update was requested, but snapshots " +
"are locked under CI — record locally and commit the file",
sourceLocation: sourceLocation)
return
}
try? FileManager.default.createDirectory(
at: snapshotURL.deletingLastPathComponent(),
withIntermediateDirectories: true)
try? value.write(to: snapshotURL, atomically: true, encoding: .utf8)
}
Reading it against the three properties: the assertion is one line at the call site; the file path is derived from suite + test with a per-test auto-incrementing counter (__1, __2, …); a missing file records and passes on first run; UPDATE_SNAPSHOTS=1 re-records everything; and under CI, both the missing-file path and update mode fail instead of writing - the same lock the gem calls lock_snapshots. Values are raw strings in .snap.txt files rather than the gem’s .snap.yaml, because the YAML serializer is deliberately not ported: callers canonicalize to a string (pretty-printed JSON, joined lines), and structured-value overloads wait until a real consumer needs one.
The flag side is a few lines in the existing test runner script, using the TEST_RUNNER_ mechanism already proven for the golden recorder:
# Snapshot update mode: bin/unit-test --update-snapshots (or UPDATE_SNAPSHOTS=1)
# rewrites every snapshot the run touches; review the snapshots/ diff before
# committing. CI is forwarded so the helper can lock snapshots.
for arg in "$@"; do
if [ "$arg" = "--update-snapshots" ]; then
UPDATE_SNAPSHOTS=1
fi
done
if [ "$UPDATE_SNAPSHOTS" = "1" ]; then
export TEST_RUNNER_UPDATE_SNAPSHOTS=1
fi
if [ -n "$CI" ]; then
export TEST_RUNNER_CI="$CI"
fi
Note the last block: the CI lock does not work by accident. GitHub Actions sets CI in the runner shell, but only TEST_RUNNER_-prefixed vars cross into the test process - so plain CI never arrives unless the script forwards it explicitly. Miss that and the lock silently never engages, which is the worst kind of safety feature.
A port is not a transliteration; the destination framework’s semantics reshape three details.
Parallel by default. Minitest runs a suite’s tests in one process where a simple counter suffices. Swift Testing runs tests in parallel by default, so the __N auto-numbering counter must be a lock-guarded dictionary keyed by suite + test. Calls within one test are sequential, so numbering stays deterministic per test - the lock only defends the map against concurrent tests touching it.
Parameterized tests collide. @Test(arguments:) runs one function many times, and every invocation shares the same #function string - so auto-numbering across parameterized cases would depend on execution order. Parameterized tests must pass an explicit named: argument; that’s a documented requirement on the helper rather than runtime machinery.
One spelling flagged for verification. The sourceLocation: SourceLocation = #_sourceLocation default argument - which makes failures point at the caller’s line rather than the helper’s - is the documented pattern for custom assertion helpers, but the plan explicitly marks it Verify: against the toolchain’s Swift Testing version before implementation. Design records should carry their own uncertainty; an implementing agent that hits a compile error on that line should find the plan already told it this might happen.
The existing golden-table system stays. Its value is compile-enforced exhaustiveness - the table is generated Swift covering allCases of language x format intent, so a newly added case cannot be silently missing from coverage. File snapshots can’t match that property, and the plan records keeping it as a decision, not an oversight. The helper is for everything that today isn’t worth a bespoke recorder: sync payload shapes, widget timeline dumps, notification content, and draining a couple of standalone validator tools into env-gated report-generating tests.
xcodebuild, readable diff-on-fail - all had existing in-repo proofs. The dependency would have bought ergonomics, and ergonomics are the cheap part.xcodebuild world, the CI variable doesn’t reach the test process unless you forward it under the TEST_RUNNER_ prefix. A lock that never engages looks identical to a lock that works.Prompt 1: “see recent work in ~/Code/helloweather, perhaps a blog post about our opus 4.8 agents and why we decided to do that? perhaps something about the swift testing + snapshots inspired by minitest-snapshots? anything else? bring me a list of potential post ideas for review.”
Prompt 2: “skip 4, 5, 6, 9 but create posts for each of the others in the 1-9 list. also add Four Answers to One Question, and Write the Rule, Not the Story – show me a concise version of your plan and then I can approve” — then “proceed, one pr per post”
Research by one Claude agent per repo mining git history since the previous post; this draft was written by a dedicated agent from that research plus the underlying commits and skill files, then reviewed before publishing.
]]>Hello Weather syncs settings from the phone to the Apple Watch over WatchConnectivity. The implementation looked reasonable when it was written:
enum Keys: String, CaseIterable {
case temperatureUnit
case displayLanguage
case memberEntitlement
// ...and eighty-some more
}
nonisolated var keys: [String] {
Keys.allCases.map { $0.rawValue }
}
func getDictionaryRepresentation() -> [String: Any] {
store.dictionaryRepresentation().filter { (key, _) in keys.contains(key) }
}
One enum listed every key in the shared app-group UserDefaults. That same enum silently doubled as the watch sync manifest. Every key registered for storage was automatically enrolled in transfer, and that dictionary shipped on every updateApplicationContext and every complication refresh.
Nobody decided this. It’s what CaseIterable does when you use it as a schema.
Four years of feature work later, the payload was about 90 keys and rising. Riding along on every complication update:
The trigger was a new preview cache. Adding a normal storage key for a phone-only screen quietly enlisted it into every watch transfer. That’s when the shape of the bug became obvious: storage registration was implying sync enrollment, and there was no place in the codebase where anyone was asked to decide.
The fix isn’t interesting. The method is.
Before writing any code, we mapped every one of the ~90 keys to actual reads and writes in the watch-compiled source set — not “does the watch have this file”, but “is this file a member of the watch target”, using the target’s file-membership exceptions in project.pbxproj as ground truth. Each key got one of three verdicts: read on watch, written on watch, or neither.
The result: roughly 25 keys belonged. About 50 were pure payload — bytes that had never been read on the other side of the connection. The rest were judgment calls that only surfaced because we were forced to write down a reason for each key.
Three findings that a quick eyeball would have gotten wrong, in both directions:
Six notification toggles looked phone-only. They aren’t. Each maps to an iOS notification category, so excluding them was the obvious call. But a helper ORs all six into a single “notifications on?” boolean, and the watch’s location service branches on it — requestAlwaysAuthorization() versus requestWhenInUseAuthorization(). Dropping six booleans would have silently downgraded the watch’s location authorization request for every user with notifications enabled. Six bytes, real consequence.
A key written on the watch but never read there. The watch stores the device location, then geocodes its own copy anyway; every reader of the stored value is phone-only UI. It’s a genuine trim candidate — and we kept it, because dropping it is an unforced behavior change with no upside. “Unused” and “safe to remove in this PR” are different questions.
A flag whose only reader is compiled out today. The feature it gates isn’t available on watchOS yet, so the read sits inside a #if canImport(...) that never fires there. But the code path that consults it runs unconditionally in watch context, so the key goes live the day the framework arrives. Enrolled ahead of time.
We also wrote down the high-risk keys explicitly, because their failure modes are silent rather than loud: entitlement flags, the language key (a localization helper reads the store directly, so losing it reverts the whole watch to English), the chart-style key (a style resolver reads the store directly, bypassing the settings manager), and the API parameter keys the watch uses to build its own forecast URL.
Two mechanics of the old protocol shaped the design, and both had to be verified rather than assumed.
The payload unions registered defaults. dictionaryRepresentation() returns every key that has a registerDefaults entry, whether or not a user ever touched it. The sync wasn’t “everything the user changed” — it was “everything the app ever declared.”
Absence meant deletion. The apply side cleared every known key before writing the incoming values:
nonisolated func setDictionaryRepresentation(_ dictionary: [String: Any]) {
for key in keys {
store.removeObject(forKey: key) // wipe everything...
}
for (key, val) in dictionary {
store.set(val, forKey: key) // ...then restore what arrived
}
}
A key missing from the payload was erased on the watch. And on this codebase, absence has semantics:
var paidWatch: Bool {
if store.object(forKey: SavedDataManager.Keys.memberEntitlement.rawValue) == nil {
return true // no entitlement key at all: treat as paid
} else {
return paid || legacyMember
}
}
That return true is deliberate — it keeps the watch app working during the window before the first sync lands, rather than flashing a paywall at a paying customer. But combine it with wipe-then-apply and you get a landmine: any allowlist that omits the entitlement key hands out the paid watch app for free. Get the polarity backwards on a different key and you revoke it from someone who paid. A one-line mistake in a list of key names, and the app’s business model is a coin flip.
So the allowlist and the deletion semantics had to change in the same commit. The shipped shape:
enum Keys: String {
// ...all ~90 storage keys...
// Watch sync is opt-in: see plans/watch-sync-allowlist.md before adding here.
static let synced: Set<Keys> = [
.weather,
.selectedLocation,
.memberEntitlement,
.legacyMember,
.temperatureUnit,
.displayLanguage,
.chartStyle,
// ...36 in total
]
}
nonisolated private static let syncedKeys = Set(Keys.synced.map(\.rawValue))
func syncPayload() -> [String: Any] {
store.dictionaryRepresentation().filter { (key, _) in Self.syncedKeys.contains(key) }
}
nonisolated func applySyncPayload(_ payload: [String: Any]) {
for key in Self.syncedKeys {
store.removeObject(forKey: key)
}
for (key, val) in payload where Self.syncedKeys.contains(key) {
store.set(val, forKey: key)
}
}
Three changes worth separating, because each does distinct work:
We also dropped CaseIterable from the enum. There were zero remaining uses, and allCases was the exact footgun being removed — leaving it available is leaving the trap armed for whoever needs “a list of all the keys” next.
The allowlist is covered by tests, and the interesting one is not the count assertion:
@Test("Local-only keys stay out of the payload")
func localOnlyKeysExcluded() {
let excluded: [SavedDataManager.Keys] = [
.debugMode, .migratedVersion, .previewCache,
.fetchInProgressAt, .savedPlaces, .recentPlaces,
]
for key in excluded {
#expect(SavedDataManager.Keys.synced.contains(key) == false,
"\(key.rawValue) must not sync to the watch")
}
}
@Test("syncPayload filters to the allowlist")
func syncPayloadFiltersToAllowlist() {
let store = SavedDataManager.shared.store
let marker = "testOnlyUnknownKey"
store.set("junk", forKey: marker)
defer { store.removeObject(forKey: marker) }
let payload = SavedDataManager.shared.syncPayload()
#expect(payload[marker] == nil)
#expect(payload[SavedDataManager.Keys.temperatureUnit.rawValue] != nil)
}
A count test says “36.” The exclusion test says why — it names the keys whose presence would be a bug and fails with a sentence a future reader can act on.
Halfway through mapping keys to reads, one key came back with an answer that didn’t fit the categories: the data-source preference was written on the watch.
Which raised an immediate question, because the sync is one-directional. The watch’s sync() only reloads complications; its requestSync() pulls phone state. There is no watch-to-phone data path at all.
So a source picked on the watch was reverted by the next phone sync. Always. The write went into the shared store, looked like it worked, and got wiped the next time the phone said anything.
The reflex is to build the missing direction. We didn’t, for two reasons.
First, we checked whether anyone could actually reach the picker — and they couldn’t. The picker view had been unreachable since 2024, when the button that presented it was turned into a display-only label. The bug was real but latent: dead code with a live-looking failure mode, sitting in the repo for nearly two years.
Second, even if it had been reachable, “add a watch-to-phone settings channel” is a transport project, not a bug fix. Building a reverse sync channel to serve one picker nobody had asked for would have been the tail wagging the dog.
So we deleted the picker. The read-only source label stays; the dead view is gone. The restore path is written down instead of built — watch source selection is a phase of the watch-parity plan, explicitly gated on the watch-to-phone settings channel that a different plan owns, and if it comes back it comes back with the Automatic option the phone has.
Delete the UI that lies. A control that appears to work and silently reverts is worse than no control. When you find one, the choice is fix the plumbing or remove the control — and removing it is legitimate, as long as you write down what restoring it would require.
The payload went from ~90 keys to 36 — and the excluded set is where the weight was: the transaction cache, both location arrays, the delivered-alerts record, the preview cache. Transfers on the complication path carry the settings the watch reads and nothing else.
The entitlement landmine is defused. The allowlist can no longer wipe a key it doesn’t list, so an omission is now a missing-setting bug instead of a free-paid-app bug. That’s the change that mattered most: not the bytes, but converting a silent revenue failure into a visible, boring one.
Two riders came out of the audit for free. A key that had been a hardcoded literal since 2024 and never touched the store at all was deleted. And the watch, on first touch of a shared manager, was writing an iOS paywall timestamp into the shared store — harmless under wipe-everything semantics because the next sync erased it, but permanent under clear-only-synced. Changing the deletion rule turned a self-correcting accident into a persistent one, so it’s now compiled out with #if !os(watchOS).
One consequence we accepted rather than fixed: watches that already synced the ~50 excluded keys keep them frozen in their local store forever. Nothing sends them and nothing clears them anymore, so the win is transfer-only. It’s correctness-neutral — none of them is read on the watch — and a one-time purge is written down as an optional follow-up rather than shipped speculatively.
The last piece is documentation, because the inversion has a cost that only shows up months later. Opt-in means a new key that the watch genuinely needs will silently not arrive. So the feature-flags skill grew a sixth touch point:
| Step | Pattern |
|---|---|
| Watch sync | Only if watch-compiled code reads the flag: enroll it in Keys.synced, else skip — keys do NOT sync automatically |
When you invert a default, the new default’s failure mode moves. Denylist fails by shipping too much. Allowlist fails by shipping too little — quietly, in a target you’re not looking at. That’s a strictly better failure to have, and it still has to be written down where the next person will hit it.
nil check has a default that was written for a different situation than the one your sync protocol creates.CaseIterable was the point of the change, not a tidy-up. As long as allCases exists, someone will reach for it.Prompt 1: “it’s been a while since we added any blog posts, see recent work in the ~/Code/helloweather projects, dispatch opus agents to search for interesting stuff that we’ve done since the last blog post, perhaps one or more agents per repo, then review and consider and come up with a proposed list of blog posts we might consider.”
Prompt 2: “draft posts for [the approved shortlist] – create one pr for the repo main / skills update we just did, then one pr per post for the approved list”
Research by one Claude agent per repo mining git history since the previous post; this draft was written by a dedicated agent from that research plus the underlying commits and plan docs, then reviewed before publishing.
]]>The Apple Watch app for Hello Weather had a Digital Crown that didn’t reliably scroll.
Not “never scrolled” — that would have been easy. It scrolled sometimes. After a finger drag but not before one. From the app list but not from a complication. It went dead after a refresh, and dead again after dismissing an error alert. It never worked at all inside pushed detail screens, or on the root screen after you navigated back.
One customer report finally described the mechanism instead of the symptom: on a large watch, the crown was never dead. Turning it silently flung the horizontal “Coming up” hourly strip about thirty hours sideways. On a smaller watch the strip sits below the fold, so the same behavior just reads as “the crown does nothing.”
That single detail reframed everything. The crown wasn’t unfocused. It was focused on the wrong thing.
Over seven months, each symptom got its own patch. The vertical scroll view got
@FocusState and a focus-on-appear. Then alerts appearing at launch caused a focus
race, so an onChange refocus was added. Then focus didn’t stick after an idle launch,
so the single retry became a ladder of three, with a defocus-then-refocus reset in the
middle. Then a scenePhase handler, because returning from the background lost focus
again. Then an alert-dismissal handler, because error alerts stole it too.
By July, ForecastView looked like this:
struct ForecastView: View {
@Environment(\.scenePhase) private var scenePhase
private static let focusRetryIntervalsNanoseconds: [UInt64] = [0, 150_000_000, 500_000_000]
private static let focusResetDelayNanoseconds: UInt64 = 25_000_000
@FocusState private var isScrollViewFocused: Bool
@State private var focusRetryTask: Task<Void, Never>?
@State private var isViewVisible: Bool = false
// ...
private func refocusScrollView() {
guard isViewVisible else { return }
focusRetryTask?.cancel()
focusRetryTask = Task { @MainActor in
for interval in Self.focusRetryIntervalsNanoseconds {
try? await Task.sleep(nanoseconds: interval)
guard Task.isCancelled == false, isViewVisible else { return }
await setScrollViewFocus()
}
focusRetryTask = nil
}
}
private func setScrollViewFocus() async {
isScrollViewFocused = false
try? await Task.sleep(nanoseconds: Self.focusResetDelayNanoseconds)
guard Task.isCancelled == false, isViewVisible else { return }
isScrollViewFocused = true
}
}
Three magic intervals. A defocus/refocus cycle with a 25ms gap. A cancellable task tracking view visibility by hand. Four separate triggers calling into it.
Every pushed detail screen carried its own three-line version of the same idea:
@FocusState private var isScrollViewFocused: Bool
var body: some View {
ScrollView(.vertical, showsIndicators: false) {
// ...
}
.focusable()
.focused($isScrollViewFocused)
.onAppear { isScrollViewFocused = true }
}
None of it worked completely. Each patch fixed the case it was written for and left the others alone.
Two things broke the stalemate.
We stopped trusting the folklore that the simulator can’t reproduce crown bugs. It
can. The trick is that plain scroll-wheel events don’t register as crown input — you
have to post continuous-phase scroll events (began/changed/ended), validated
against the watch’s own Settings app as a control. That turned every experiment from a
device session into a simulator run.
And we tested with crown-only input, before any touch. Every prior QA pass had tapped or dragged something first, which silently rebound the crown and hid the launch state. Two structural findings fell out immediately.
watchOS binds the Digital Crown to exactly one scrollable at a time. A horizontal
ScrollView nested inside the vertical one is still a scroll view — and at launch, it
won. Crown rotation drove the hourly strip sideways instead of scrolling the page.
The important part: .focusable(false) does not prevent this. Neither does removing
the strip’s programmatic scrollTo. The nested scroll view claimed the crown merely by
existing. Every launch-path workaround was fighting for ownership that the layout was
handing away.
This one was more embarrassing. The detail screens had never crown-scrolled — a
long-standing bug that survived eight-plus experiments across two research sessions,
including @FocusState reclaim, .focusable(interactions: .edit), NavigationStack
migration, and .id-nonce view recreation.
All of those experiments assumed the focus machinery was part of the solution. It was
the problem. Remove .focusable()/.focused()/onAppear-focus from a pushed
ScrollView and watchOS routes the crown to it natively, immediately, in every case.
There’s a signal buried in that: Apple’s own documented crown examples never put a raw
focusable ScrollView in the happy path. When your configuration appears nowhere in the
platform’s sample code, that’s evidence, not coincidence.
We did the upstream homework before committing to a rewrite: OS release notes, beta notes, and the year’s SwiftUI session content contained zero crown focus-ownership changes, while adjacent crown and scroll-view bugs were being triaged. The same complication-launch failure reproduced in a first-party Apple app. Verdict: nothing is coming from the platform. Fix it ourselves.
The change removed both root causes and every workaround built on top of them:
ScrollView became a clipped HStack panned by a
DragGesture.ScrollView bound the crown natively —
so all the focus machinery went, along with the scenePhase and alert refocus
handlers..focusable()/.focused()/focus-on-appear
blocks.Net: 391 lines added, 122 removed — and nearly all of the additions are the hand-rolled
pan, not new crown logic. ForecastView ended up simpler than it had been before the
first workaround shipped.
Replacing a ScrollView means replacing its physics. The strip tracks an offset, clamps
it to content width, and applies UIScrollView-style exponential velocity decay after
release:
private var horizontalDragGesture: some Gesture {
DragGesture(minimumDistance: 8)
.onChanged { value in
decelerationTask?.cancel()
guard dragStart != value.startLocation else { return }
dragStart = value.startLocation
dragAxis = abs(value.translation.width) > abs(value.translation.height) ? .horizontal : .vertical
}
.updating($dragOffset) { value, state, _ in
guard dragAxis == .horizontal else {
state = 0
return
}
state = value.translation.width
}
.onEnded { value in
guard dragAxis == .horizontal else { return }
var transaction = Transaction()
transaction.disablesAnimations = true
withTransaction(transaction) {
scrollOffset = clampedScrollOffset(scrollOffset + value.translation.width)
}
decelerate(initialVelocity: value.velocity.width)
}
}
private func decelerate(initialVelocity: CGFloat) {
decelerationTask?.cancel()
guard abs(initialVelocity) > 50 else { return }
decelerationTask = Task {
var velocity = initialVelocity
var lastTick = ContinuousClock.now
while abs(velocity) > 12 {
guard (try? await Task.sleep(for: .milliseconds(16))) != nil else { return }
let now = ContinuousClock.now
let dt = min(lastTick.duration(to: now) / .seconds(1), 0.05)
lastTick = now
let unclamped = scrollOffset + velocity * dt
scrollOffset = clampedScrollOffset(unclamped)
if scrollOffset != unclamped { break }
velocity *= pow(0.998, dt * 1000)
}
}
}
Three details worth stealing:
velocity *= pow(0.998, dt * 1000) gives
identical physics whether the loop ticks at 60Hz or drops frames. A flat per-frame
constant does not.dt. min(dt, 0.05) keeps a resuming app from teleporting the strip to the
far edge on its first tick.startLocation, not by a reset in onEnded. Cancelled gestures
never call onEnded, so reset bookkeeping there goes stale and deadens the next pan.
Keying the latch to the start location means every gesture re-latches and there’s
nothing to clean up.Every case in the matrix, exercised with crown-only input before any touch:
| Case | Before | After |
|---|---|---|
| Cold launch | Dead vertically; crown flings the hourly strip | Scrolls the page |
| Successful refresh | Dead | Works |
| Failed refresh → alert → dismiss | Dead | Works |
| Crown right after swiping the strip | Crown drives the strip | Scrolls the page |
| Crown inside pushed detail screens | Dead | Works |
| Crown on root after Back | Dead | Works |
One accepted trade-off, found only by hostile runtime QA rather than code review: a
vertical page flick that starts on the strip is occasionally swallowed, because on
watchOS a descendant DragGesture starves the outer scroll view’s pan.
.simultaneousGesture, plain .gesture, and a larger minimumDistance all behave
identically. We shipped it anyway — the failure is visible and self-healing (flick again
from anywhere else), which is strictly better than a dead crown that gives no feedback
at all.
.focusable(false) won’t save
you. If the crown feels haunted, count your scroll views. And if the platform would
route it correctly on its own, taking focus manually makes things worse, not safer.Prompt 1: “it’s been a while since we added any blog posts, see recent work in the ~/Code/helloweather projects, dispatch opus agents to search for interesting stuff that we’ve done since the last blog post, perhaps one or more agents per repo, then review and consider and come up with a proposed list of blog posts we might consider.”
Prompt 2: “draft posts for [the approved shortlist] – create one pr for the repo main / skills update we just did, then one pr per post for the approved list”
Research by one Claude agent per repo mining git history since the previous post; this draft was written by a dedicated agent from that research plus the underlying commits and plan docs, then reviewed before publishing.
]]>Fanning out parallel coding agents is easy. Getting a mergeable result out the other end is not.
Run twenty agents at once on the same repo and you get the same four failures every time:
The instinct is to fix this with better judgment — a smarter reviewing agent, a stricter prompt, more careful reading. That doesn’t scale, because judgment is exactly the resource you ran out of.
What does scale is structure. Below are two runs from Hello Weather that used the same five-phase shape: an iOS visual-style catalog that went from 41 to roughly 168 entries in about a month, and an Android translation pass that produced 191 strings across 27 locales.
One research agent per aesthetic cluster — graphic-design movements, retro computing and games, transit and wayfinding signage, print and paper craft, instruments and broadcast hardware. Each agent uses web search rather than memory alone, and each returns briefs in an identical shape:
- Name + one-line identity (the elevator pitch)
- Grounding: the specific real works/rules/hardware, era-accurate details with sources
- Palette: 4-8 hex values; flag interpretive hexes honestly when no official spec exists
- Typography: system-font approximations
- Section mapping: hero / hourly / daily / stats, concrete and clever
- Signature element to nail: the one thing that makes it instantly recognizable
- Feasibility and wow factor
- Distinctness check vs the existing catalog
The schema is doing two jobs. It makes briefs comparable to each other, so a human can rank thirty of them in one sitting. And it makes briefs executable — a downstream implementation agent gets the palette, the typography, and the section mapping without having to invent any of it.
Then a quality bar, stated as one sentence:
The quality bar: the DATA wears the aesthetic. The best ideas make the forecast become the artwork, not decorate it. Reject briefs where the style is only chrome around a generic chart.
That single line kills more bad output than any amount of code review. It’s a filter applied at the idea stage, where rejecting something costs nothing.
There is also an explicit constraint in the brief format worth stealing verbatim for any project that draws on cultural reference:
IP cautions: evoke grammar, never copy sprites/logos/mascots/likenesses.
A visual grammar — a palette, a grid, a typographic register, a way of drawing a dial — is fair game. The specific artwork is not. Making that a required field in the brief means every idea gets checked against it before anyone writes a line of code, rather than after.
Research agents produce one ranked list. Then everything stops.
Synthesize into one ranked list and stop for discussion. No task lists, no worktrees, no implementation until the set is picked.
This is the cheapest phase in the pipeline and the highest leverage. Ideas that get cut here cost minutes. Ideas that get cut after implementation cost an agent-hour each and a pile of merged code that has to come back out. Light sketches that survive the cut get sent back for a second research round to become full briefs before implementation.
This is the phase that eliminates merge conflicts, and it is the one most easily skipped.
Before any implementation agent launches, the orchestrator adds every new entry to every shared file: the enum and its display-name switch, the view dispatch, the styling extensions, and — the trap that broke the first run — the two exhaustive switches in the widget and watch targets, which need an explicit arm per case or the build fails.
For dozens of entries at once, hand-editing six files is a mistake. A Python codemod with per-insertion assertions does it instead:
For large packs, a Python codemod with per-insertion assertions (fail loudly on a missing anchor, print per-file counts) beats dozens of hand edits.
The assertions matter more than the automation. A codemod that silently no-ops on a missing anchor is worse than a hand edit, because it produces a plausible-looking diff with a hole in it. Fail on the missing anchor, print a per-file insertion count, and compare that count to what you expected.
Once central wiring lands, every shared file is done. Implementation agents are told, as a hard rule, that they may only create files inside their own folder. Twenty agents, zero overlapping writes, zero conflicts — not because the agents coordinated, but because there was nothing left to coordinate over.
The fan-out prompt is a template, and its most important property is that it is repetitive:
Restating the rules in full for every single agent feels redundant when you’re writing the dispatcher. It isn’t. There is no shared memory between parallel agents; a rule stated once in a document that an agent may or may not read is a rule that holds maybe 80% of the time. Eighty percent across 67 units is thirteen violations.
Note the last line: agents do not build. One build at the end, by the orchestrator, is far cheaper than twenty agents each spinning up a compiler and each trying to fix errors in shared state.
Concurrency has a practical ceiling — around 20 agents in flight, with the rest queued and dispatched as completions free up slots.
The most valuable single lesson from the whole exercise:
Verify-then-repair: agents can die mid-write (API errors, spend limits). Survey folders: entry view present +
swiftc -parseclean → keep; clearly partial → delete the folder and relaunch fresh. Never assume a completion.
Treat the fan-out as unreliable by construction. After every batch, enumerate what should exist, enumerate what does exist, diff the two, and relaunch the gaps from scratch. Not repair — relaunch. A half-written unit is cheaper to delete and redo than to diagnose.
Then mechanical audit greps across all new folders, looking for the rules that were supposed to hold: comment lines, force-unwraps and force-casts, non-verbatim string constructors, raw index access. Every one of those is a regex, not a judgment call.
Only then: one build, fix only clearly-diagnosed errors, one commit, human QA pause, then push.
Everything above makes the fan-out produce a lot of code. The isolation contract is what makes it safe to merge a lot of fast-written code.
The catalog is debug-only. It is never shipped to users; there is no user-facing picker, and the whole thing sits behind an internal debug gate. The default path renders production views and is untouched. That’s the starting point, but on its own it isn’t enough, because shared helper code is still a coupling channel — and coupling is what turns 81,000 lines of throwaway-quality code into a permanent tax on the production codebase.
So the contract says: shared style components are copies, never references.
Styles work makes minimal-to-zero production changes, so production features can launch and evolve without worrying about styles. Everything under the shared styles directory is copies — fork in-flux production views as prefixed types (mechanical copy first, tokenize second); never reference or modify them from shared style code.
Two bounded exceptions, both deliberate: a style’s own scroll view may call stable production leaf views read-only, and the alerts view is always reused by reference, because the safety-critical surface must have exactly one implementation.
Copies are usually the wrong instinct. Here they’re the entire point. Production charts were mid-rewrite during all of this. If the catalog referenced them, every production change would have had to be validated against 168 downstream consumers of unknown quality. Because the catalog holds copies, the production rewrite shipped without ever considering them.
The rest of the policy follows from that:
And the partition is verified by a test rather than by discipline. Every entry must belong to exactly one bucket — production, near-shipping, kept, pending-deletion:
@Test("Every style belongs to a group")
func groupsCoverAllStyles() {
let all = Set(SettingsManager.ForecastStyle.allCases)
let union = SettingsManager.ForecastStyle.styleGroupSets
.reduce(into: Set<SettingsManager.ForecastStyle>()) { $0.formUnion($1.1) }
#expect(all.subtracting(union).isEmpty)
}
@Test("Production is exactly the default style")
func productionIsTheDefault() {
#expect(SettingsManager.ForecastStyle.productionStyles == [.helloWeather])
}
Coverage, disjointness, exact count, and “production contains exactly one thing.” Adding an entry without classifying it fails the test. The isolation boundary is an assertion, not a convention.
Fan-out produces work nobody has profiled, and two problems showed up repeatedly:
drawingGroup() per row to collapse compositing layers.rotation3DEffect at exactly ±90° with perspective produces a degenerate transform and logs “ignoring singular matrix” every frame. Clamp to ±89.9°.Also: hold any entrance choreography until loading clears, so animation never fights launch and refresh work.
The same shape, a completely different domain, and a much sharper verifier.
The task: translate 191 Android strings into 27 locales. One agent per locale, 27 in parallel.
The brief-schema equivalent was an anchor rather than a template. Each agent was pointed at the sibling iOS app’s professionally-reviewed translation file and told to match its terminology for the same locale. That single anchor removes the largest source of variance in parallel translation — twenty-seven agents independently deciding how to render “feels like” or “chance of rain.” The terminology decisions were already made, by humans, and paid for.
Central wiring came first, exactly as in the iOS case: a separate, behaviorally inert commit declaring all 28 locales in the locale config, wiring the per-app language picker, and adding the AppCompat service that persists the user’s choice across OS versions. No translation files in that commit at all. With English-only resources present, it changes nothing — which is the point. The shared configuration file was finished and merged before a single translation agent ran.
The verifier is completely mechanical. Every locale must pass:
name attributes)%1$s, %d, %1$.0f, %% — present, correct, and in the right order@, entities or CDATA for ampersands and ellipsesNot one of those checks requires reading the translation. That’s the design goal. A parallel pipeline needs a gate that says yes or no without a human in the loop, and “does this Czech sentence read well” is not that gate. Key-set equality is.
The residual risk is real and named rather than pretended away: mechanical checks confirm structural correctness, not fluency. Professional post-editing is planned as a separate pass. The verifier’s job is to guarantee nothing is broken, not to guarantee everything is good.
The platform wrinkle is the interesting part, and it’s the isolation contract showing up in an unfamiliar costume. Android auto-enables any values-XX/strings.xml present in the build:
Android automatically enables any
values-XX/strings.xmlpresent in the build — unlike iOS, there is no debug-only option. Only create translation files when ready to ship them to all users.
There is no debug gate available. Merging the branch is the launch. So the branch itself became the isolation boundary: it stays a deliberate draft, complete and verified and unmerged, until someone decides to ship localization. The commit message says so explicitly.
That’s the general lesson. Every fan-out needs a boundary that lets fast-produced output exist without being live. On iOS it was a debug flag plus a copy-not-reference rule. On Android the platform refused to provide one, so the boundary moved up a level to version control. What matters is that the boundary exists and is written down — not which layer it lives at.
Prompt 1: “it’s been a while since we added any blog posts, see recent work in the ~/Code/helloweather projects, dispatch opus agents to search for interesting stuff that we’ve done since the last blog post, perhaps one or more agents per repo, then review and consider and come up with a proposed list of blog posts we might consider.”
Prompt 2: “draft posts for [the approved shortlist] – create one pr for the repo main / skills update we just did, then one pr per post for the approved list”
Research by one Claude agent per repo mining git history since the previous post; this draft was written by a dedicated agent from that research plus the underlying commits and skill files, then reviewed before publishing.
]]>Localized UI truncation is discovered by customers, not by developers. The loop looks like this:
The reason this loop is so slow is that nothing in the toolchain knows how wide a string will be. A localization catalog stores text. A SwiftUI layout computes widths at runtime, on device, in a specific font at a specific Dynamic Type size. The two facts never meet until a human looks at a screenshot.
Worse, the truncation is systemic rather than incidental. If Air Quality overflows a stat card title in Vietnamese, it overflows in the widget too, because it’s the same catalog key in the same slot class. And if the string comes from your server - a level name, an advisory phrase - then even a one-word fix requires an app release that has nothing to do with the app.
At Hello Weather we hit all of it at once: customer QA reported cut-off text in the small stat cards, in Spanish. Rather than fix the Spanish strings, we went looking for a way to know, ahead of time, every string in every language that would not fit.
The pattern has three parts, and none of them require running the app:
Plus a lifecycle: the validator starts in audit mode (report findings, exit 0) while there’s a backlog, then flips to gate mode (non-zero exit) once the backlog is cleared.
We built this twice. The first generation counted characters. The second generation measured actual rendered widths. Both were useful, and the difference between them is the interesting part.
The registry is a plain JSON file, committed to the repo:
{
"_readme": "Width budgets for catalog keys rendering in width-constrained slots (stat cards, chart legends, widget rows, complication labels). budget = max Character count for every language value except cjkExempt. scales = per-language values within one group must stay pairwise distinct.",
"cjkExempt": ["ja", "ko", "zh-Hans", "zh-Hant"],
"keys": {
"Air Quality": { "slots": ["statTitle"], "budget": 17 },
"Cloudy": { "slots": ["chartLegend"], "budget": 9 },
"AQI": { "slots": ["complicationLabel"], "budget": 6 },
"Actual": { "slots": ["miniTitle"], "budget": 9 }
},
"scales": {
"uvLegend": ["Low", "Mid", "High", "Max"],
"pressureLegend": ["Low", "Normal", "High"],
"visibilityLegend": ["Good", "Fair", "Poor"]
}
}
Seventy-four keys across six slot classes. Two things are encoded here that a linter couldn’t infer.
Slot classes. A key is constrained because of where it renders, and one key can render in several places. Writing the slot down makes the budget reviewable - someone can ask “is 17 characters really the stat title budget?” without reading layout code.
Scale groups. These are sets of labels that appear together in one chart legend. The rule isn’t about length at all: within a scale, every language’s values must be pairwise distinct. A translator working key-by-key has no way to know that two English words map to the same natural word in their language.
That second rule found two live shipping bugs on the very first run:
Cloudy and OvercastHigh and MaxTwo identically-labeled swatches, different colors, in a chart that shipped. No amount of width measurement would have caught those; no reviewer scanning a translation file key-by-key would have either.
The validator is about 90 lines of Foundation. It parses the registry and the localization catalog as plain JSON - no app dependency, no test target:
for scale in scales.keys.sorted() {
for language in checkedLanguages {
var seen: [String: String] = [:]
for key in scales[scale] ?? [] {
guard let translated = value(key, language) else { continue }
if let previous = seen[translated] {
findings.append("FINDING: within-scale duplicate in \(scale) " +
"\(language): \"\(previous)\" and \"\(key)\" " +
"both \"\(translated)\"")
} else {
seen[translated] = key
}
}
}
}
A bash wrapper compiles it to a temp directory and runs it, so the whole tool is ./tools/validate-compact-strings with no build system involvement:
#!/usr/bin/env bash
set -euo pipefail
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/compact-string-validation.XXXXXX")"
trap 'rm -rf "$tmp_dir"' EXIT
swiftc -parse-as-library "$script_dir/validate-compact-strings.swift" -o "$tmp_dir/validator"
TOOLS_DIR="$script_dir" "$tmp_dir/validator"
First run: 211 findings across 26 languages. That number is not a failure - it’s a work-list, ordered and diffable.
Character counts are a proxy, and a bad one. Ω and l are both one character. Cyrillic is wider than Latin at the same count. And a character budget can’t express the difference between a 13pt regular description and an 11pt semibold uppercased title in the same card.
So the second validator measures real rendered widths using AppKit text measurement on the desktop, with macOS SF Pro standing in for iOS SF Pro:
static func width(_ string: String, _ size: CGFloat, weight: NSFont.Weight = .regular) -> CGFloat {
let font = NSFont.systemFont(ofSize: size, weight: weight)
return ceil(NSAttributedString(string: string, attributes: [.font: font]).size().width)
}
The budget side is the part worth copying. Instead of a hand-picked number, it re-derives the layout from the actual grid formula the SwiftUI view uses:
static let deviceWidth: CGFloat = 375 // smallest supported width
static let gridOuterPadding: CGFloat = 32
static let gridSpacing: CGFloat = 10
static let gridMinimumColumn: CGFloat = 165 // adaptive grid minimum
static let cardPadding: CGFloat = 32
static let iconAllowance: CGFloat = 36
static let headroom: CGFloat = 0.95 // proxy-font margin
static var descriptionBudget: CGFloat {
let available = deviceWidth - gridOuterPadding
let columns = floor((available + gridSpacing) / (gridMinimumColumn + gridSpacing))
let column = (available - (columns - 1) * gridSpacing) / columns
return column - cardPadding
}
static var titleBudget: CGFloat { descriptionBudget - iconAllowance }
static var passBar: CGFloat { descriptionBudget * headroom }
That yields 134.5pt for descriptions and 98.5pt for titles and subtitles. Because the formula mirrors the view, a layout change to spacing or column minimum is a one-line change in the tool - not a re-guess of every budget.
The 5% headroom matters too. Desktop SF Pro is a proxy, not the real thing, so results land in three buckets rather than two: OK, MARGIN (inside the 5% band, needs device verification), and OVER.
Here’s the part that separates a real measurement tool from a toy: most constrained strings are format templates, not literals. Sunrise at %@. has no width until you fill it in. Measuring the template is meaningless; measuring it with a convenient argument is worse, because it silently passes.
So the tool synthesizes the widest legal argument for each placeholder:
// Widest clock string for this locale (both 12h and 24h are measured)
static func worstTime12(_ language: String) -> String {
formattedDate(language, pattern: "h:mma", hour: 12, minute: 59)
.lowercased(with: locale(language))
}
// Widest noun that can fill a precip template
static func worstPrecipNoun(_ language: String) -> String {
["Rain", "Snow", "Sleet", "Hail", "Precip"]
.compactMap { catalogValue($0, language) }
.max(by: { width($0, 13) < width($1, 13) }) ?? "Rain"
}
The catalog reader does the same thing for plurals - when an entry has plural variations rather than a single string unit, it returns the widest variant, not the other case:
if let plural = (localization["variations"] as? [String: Any])?["plural"] as? [String: Any] {
let values = plural.values.compactMap {
(($0 as? [String: Any])?["stringUnit"] as? [String: Any])?["value"] as? String
}
return values.max(by: { width($0, 13) < width($1, 13) })
}
The last category of argument is the important one. Many of the widest strings in the app are not in the app at all. Level names (“Very Unhealthy”), advisory phrases (“Health effects possible.”), wind bearings, and composed pollen phrases are all returned by our API, localized on the server. So the tool reads our server repo’s locale files directly, converting YAML to JSON in the wrapper and passing a directory path in:
for yml in "$web_dir"/config/locales/*.yml; do
lang="$(basename "$yml" .yml)"
ruby -ryaml -rjson -e 'puts JSON.generate(YAML.safe_load(File.read(ARGV[0])))' \
"$yml" > "$web_json_dir/$lang.json"
done
web_head="$(git -C "$web_dir" rev-parse --short HEAD)"
The report records the server checkout’s commit SHA and warns when it differs from that repo’s main branch, so a stale baseline announces itself; if the checkout isn’t present at all, the tool degrades to client-key coverage with a warning instead of failing. Rows built from synthesized rather than real values (temperatures, precip amounts, wind units) are tagged [estimate], so a reader knows which findings are inferences.
The tool writes a markdown file that is checked in:
## Summary
- Rows measured: 1620 (27 languages)
- Over budget at default type size: **483**
- Inside margin (127.8-134.5pt band): 78
- Over budget at the xxLarge cap: 674
| Card | Slot | Language | Width | Verdict | Source | Rendered |
|---|---|---|---|---|---|---|
| AQI | description | de | 242/134pt | OVER | `server:aqiLevelPhrase` | Gesundheitliche Auswirkungen moeglich. |
| AQI | description | en | 144/134pt | OVER | `server:aqiLevelPhrase` | Health effects possible. |
| AQI | subtitle | it | 134/98pt | OVER | `server:aqiLevelName` | Molto Insalubre |
Committing generated output feels wrong until you use it once. It buys three things:
git diff shows exactly which rows moved. That is the review artifact for a translation PR.It also surfaced things nobody was looking for: stat card titles truncate today (Vietnamese Chất lượng không khí at 141pt in a 98pt slot, with eight more languages over on the same key), English itself fails 9 rows, and a client bug where a .capitalized call was title-casing Spanish level names mid-sentence.
Of the 483 over-budget rows, 140 came from server-owned strings - and that’s the architectural payoff. Because those phrases live in our API’s locale files rather than in the app bundle, fixing them is a content change that deploys: no App Store review, no version gate, no waiting for users to update. A truncation bug became a copy edit.
The server-side pass shortened 300+ locale values across 22 languages, under one rule worth stealing:
The dual-surface rule: a shortened value must still read as natural prose on the app’s detail screen and on the web product - not merely fit the card.
This is what stops “make it fit” from degrading into telegraphese. A phrase like a pressure trend name has to work as a standalone card label and inside a sentence:
# before -> after, es
pressure:
trend_ext_name:
falling-quickly: "Cae rápido" # was "Bajando rápido"
falling: "Bajando"
Note that falling-quickly and falling are adjacent steps in the same scale - so the shortened value still has to stay lexically distinct from its neighbor, which is the generation-1 scale rule showing up again on the server side.
Verification closed the loop: point the client’s width tool at the server branch and re-run. Server-string findings dropped from 140 to 74.
The remaining 74 are not failures, they’re adjudicated keeps - rows where no natural short form exists, recorded explicitly:
Writing keeps down, in the same artifact as the findings, is what makes the report safe to gate on later. A row that stays over budget forever is fine as long as somebody decided that on purpose.
Measure rendered width, not character count. Characters are a useful first pass - cheap, dependency-free, and the scale-distinctness check works on them - but they can’t distinguish an 11pt semibold uppercased title from a 13pt regular description in the same card. Ship the cheap version first if it unblocks you, then replace it.
Derive budgets from the layout formula, not from taste. Copying the grid arithmetic into the tool means a spacing change is a one-line edit, not a re-guess of 74 numbers. Hard-coded budgets rot the moment somebody touches the view.
A format template has no width. Every placeholder needs a worst-case argument: widest plural variant, widest clock format for the locale, widest enumerated noun, longest real server value. Measuring %@ starting in %lldm. measures nothing.
Standalone beats integrated. A swiftc invocation on one file, wrapped in bash, runs in seconds with no project build, no simulator, no test target. That’s what makes it something you actually run on a branch before opening a PR.
Commit the report. Generated output in the repo turns into a work-list, a reviewable diff, and a baseline all at once. The diff on a translation PR is the review.
Audit mode first, gate mode later. A validator that fails on day one with 211 findings gets disabled on day two. Exit 0 while the backlog exists, then flip to a hard gate once it’s cleared - and make the flip its own change, so somebody has to decide.
Record the keeps. “Cannot be fixed without unnatural language” is a legitimate outcome. Writing it into the same report as the findings is what lets you turn the audit into a gate without lying about the remainder.
Server-owned display strings are an architecture decision with a UI payoff. Putting level names and advisory phrases in the API rather than the app bundle looked like a normalization choice. It turned out to mean a whole class of UI-fit bugs is fixable by deploy. Worth weighing the next time you decide where a string should live.
Prompt 1: “it’s been a while since we added any blog posts, see recent work in the ~/Code/helloweather projects, dispatch opus agents to search for interesting stuff that we’ve done since the last blog post, perhaps one or more agents per repo, then review and consider and come up with a proposed list of blog posts we might consider.”
Prompt 2: “draft posts for [the approved shortlist] – create one pr for the repo main / skills update we just did, then one pr per post for the approved list”
Research by one Claude agent per repo mining git history since the previous post; this draft was written by a dedicated agent from that research plus the underlying commits and tools, then reviewed before publishing.
]]>Running promotional campaigns for iOS subscriptions is harder than it looks. The naive approach - using StoreKit’s introductory offers - has a critical flaw: you can’t reliably detect eligibility.
StoreKit 2 tells you if a user is eligible for an introductory offer, but only for users who have never subscribed on the current device. It can’t see:
This creates a terrible user experience: you show someone a “50% off!” banner, they tap it, and the purchase fails or charges full price because they’re secretly ineligible.
We also wanted to launch and end campaigns without shipping app updates. Marketing shouldn’t wait for App Review.
We built a three-layer promo system:
The key insight: offer codes have no eligibility restrictions. Anyone can redeem them, which means no surprise failures.
Promo configuration lives in a YAML file on the server:
# config/appstore/pricing_strategy.yml
promo:
name: happy10
startDate: "2026-03-01"
endDate: "2026-03-31"
The API checks the date window and returns the promo key:
# app/models/api/promo.rb
class Api::Promo < Api::Base
STRATEGY_PATH = Rails.root.join("config/appstore/pricing_strategy.yml").freeze
class << self
def active(today: Time.now.utc.to_date)
promo = strategy["promo"] || {}
name = promo["name"]
return nil if name.blank?
start_date = promo["startDate"]
end_date = promo["endDate"]
return nil if start_date.blank? || end_date.blank?
date_window = Date.iso8601(start_date.to_s)..Date.iso8601(end_date.to_s)
return nil unless date_window.cover?(today)
new(name: name)
end
end
end
The weather API response includes the promo field:
{
"forecast": { ... },
"promo": "happy10"
}
To launch a campaign: update the YAML and deploy. To kill it: set name: null and deploy. No app update required.
The iOS app doesn’t blindly trust whatever the server sends. It maintains a set of supported promos:
@MainActor
class PromoManager: ObservableObject {
static let shared = PromoManager()
private static let supportedPromos: Set<String> = ["happy10"]
private lazy var weatherManager = WeatherManager.shared
private lazy var storeManager = StoreManager.shared
var promoKey: String? {
promoDebug ?? weatherManager.weather?.forecast?.promo
}
var promoActive: Bool {
guard storeManager.unpaid else { return false }
guard let promoKey else { return false }
return Self.supportedPromos.contains(promoKey)
}
}
This two-layer check serves multiple purposes:
Each promo maps to specific App Store offer codes:
let offerCode = "HAPPY10"
let offerCodeFamily = "HAPPY10FAM"
var discountPercentage: Int {
50
}
Users redeem these codes directly in the App Store - no eligibility check, no silent failures.
Users can dismiss promo banners. We track dismissal with a cooldown:
var promoDismissedAt: Date? {
get {
savedDataManager.store.object(
forKey: SavedDataManager.Keys.promoDismissedAt.rawValue
) as? Date
}
set {
savedDataManager.store.set(
newValue,
forKey: SavedDataManager.Keys.promoDismissedAt.rawValue
)
objectWillChange.send()
}
}
var showPromoTimeInterval: TimeInterval {
90 * 24 * 60 * 60 // 90 days
}
var showPromoNag: Bool {
guard promoActive else { return false }
guard let promoDismissedAt = promoDismissedAt else { return true }
return Date() >= promoDismissedAt.addingTimeInterval(showPromoTimeInterval)
}
Managing offer codes through App Store Connect’s web UI is tedious. We built a CLI skill and script system:
# List all configured offers and their ASC status
bin/appstore offer list --verbose
# Preview what would be created
bin/appstore offer apply happy10_yearly_single --dry-run --verbose
# Create the offer in App Store Connect
bin/appstore offer apply happy10_yearly_single --verbose
# Verify ASC matches expected pricing
bin/appstore offer verify happy10_yearly_single --verbose
Offers are defined in the same pricing strategy file:
# config/appstore/pricing_strategy.yml
offer_codes:
happy10_yearly_single:
product_id: hw_v4_yearly_single
reference_name: HAPPY10_20260213
offer_mode: pay_up_front
duration: one_year
number_of_periods: 1
customer_eligibilities: [new, existing, expired]
offer_eligibility: once
discount_percent: 50
enabled: true
happy10_yearly_family:
product_id: hw_v4_yearly_family
reference_name: HAPPY10FAM_20260213
offer_mode: pay_up_front
duration: one_year
number_of_periods: 1
customer_eligibilities: [new, existing, expired]
offer_eligibility: once
discount_percent: 50
enabled: true
Prices are computed from approved_prices.yml at runtime, applying the discount percentage to each territory’s base price.
# Create a custom code with redemption limit
bin/appstore offer codes custom happy10_yearly_single \
--code HAPPY10 \
--limit 5000 \
--expires 2026-03-31 \
--verbose
# Or create one-time codes for distribution
bin/appstore offer codes one-time happy10_yearly_single \
--count 1000 \
--expires 2026-06-01 \
--verbose
# Download the generated codes
bin/appstore offer codes values happy10_yearly_single \
--batch-id BATCH_ID \
--output tmp/codes.txt \
--verbose
If something goes wrong:
# Preview
bin/appstore offer deactivate happy10_yearly_single --dry-run
# Deactivate
bin/appstore offer deactivate happy10_yearly_single
A complete campaign launch:
# 1. Refresh App Store Connect data
bin/appstore refresh --verbose
# 2. Validate pricing
bin/appstore validate --verbose
# 3. Review what will be created
bin/appstore offer plan happy10_yearly_single --verbose
# 4. Create offers
bin/appstore offer apply happy10_yearly_single --verbose
bin/appstore offer apply happy10_yearly_family --verbose
# 5. Create redemption codes
bin/appstore offer codes custom happy10_yearly_single \
--code HAPPY10 --limit 5000 --expires 2026-03-31 --verbose
bin/appstore offer codes custom happy10_yearly_family \
--code HAPPY10FAM --limit 5000 --expires 2026-03-31 --verbose
# 6. Verify everything matches
bin/appstore offer verify happy10_yearly_single --verbose
bin/appstore offer verify happy10_yearly_family --verbose
# 7. Update server config and deploy
# config/appstore/pricing_strategy.yml
# promo:
# name: happy10
# startDate: "2026-03-01"
# endDate: "2026-03-31"
Offer codes solve eligibility: Unlike introductory offers, anyone can redeem an offer code. No silent failures, no confused users.
Server control enables agility: Launch campaigns with a deploy, not an app update. End them instantly if needed.
Supported promos enable safety: Old app versions gracefully ignore new campaigns. New campaigns can be tested before the app officially supports them.
CLI tooling reduces errors: Scripted offer management is repeatable and auditable. No clicking through ASC forms.
The system has successfully run multiple campaigns with zero eligibility-related support tickets.
Prompt: “create a new post about our promo system, see previous commits, note the new promo system uses ‘offer codes’ to avoid eligibility issues, such as users who previously subscribed or even had a trial were ineligible, which could not be detected with storekit2. note the lightweight server component, so we can enable/disable promos server-side. note the client side has ‘supported promos’ so we can add support and adjust UI elements etc over time. note also the appstore skill+script system which lets us manage offer codes etc with appstoreconnect. create a pr for this new post.”
Generated by Claude using the blog-post-generator skill. Based on production code from Hello Weather’s promo system.
]]>Implementing in-app purchases correctly is surprisingly complex. You need to:
StoreKit 2 simplifies much of this, but the documentation lacks complete production examples.
We built a three-layer architecture:
This separation keeps the StoreKit complexity isolated from business logic.
StoreService handles all StoreKit 2 interactions. It’s marked @MainActor for thread safety:
import StoreKit
@MainActor
class StoreService {
static let shared = StoreService()
private lazy var storeManager = StoreManager.shared
private var transactionUpdatesTask: Task<Void, Never>?
private var subscriptionStatusUpdatesTask: Task<Void, Never>?
func activate() {
Task {
await observeTransactionUpdates()
await observeSubscriptionStatusUpdates()
await checkForUnfinishedTransactions()
await updateCurrentEntitlements()
await fetchProducts()
}
}
}
The activation sequence runs in order:
StoreKit 2 provides async sequences for transaction updates:
func observeTransactionUpdates() async {
self.transactionUpdatesTask = Task { [weak self] in
for await verificationResult in Transaction.updates {
guard let self else { break }
await self.process(verificationResult)
}
}
}
func observeSubscriptionStatusUpdates() async {
subscriptionStatusUpdatesTask = Task { [weak self] in
for await status in StoreKit.Product.SubscriptionInfo.Status.updates {
guard let self else { break }
await self.process(status.transaction)
}
}
}
These run continuously, catching renewals, cancellations, and refunds even when the app is backgrounded.
Every transaction goes through cryptographic verification:
func process(_ verificationResult: VerificationResult<Transaction>) async {
switch verificationResult {
case .verified(let transaction):
let renewalInfo = await fetchRenewalInfo(transaction)
storeManager.process(transaction: transaction, renewalInfo: renewalInfo)
await transaction.finish()
case .unverified(_, let error):
// Log but don't crash - could be jailbroken device or corruption
Logger.error(error.localizedDescription)
}
}
func fetchRenewalInfo(_ transaction: Transaction) async
-> StoreKit.Product.SubscriptionInfo.RenewalInfo? {
guard let verificationResult = await transaction.subscriptionStatus?.renewalInfo
else { return nil }
switch verificationResult {
case .verified(let renewalInfo):
return renewalInfo
case .unverified(_, let error):
Logger.error(error.localizedDescription)
return nil
}
}
The renewalInfo tells you whether the subscription will auto-renew - critical for showing “Cancelling” vs “Subscribed” status.
App Store holds transactions until you call finish(). If the app crashes mid-purchase, these accumulate:
func checkForUnfinishedTransactions() async {
for await verificationResult in Transaction.unfinished {
await self.process(verificationResult)
}
}
func updateCurrentEntitlements() async {
for await verificationResult in Transaction.currentEntitlements {
await self.process(verificationResult)
}
storeManager.hasUpdatedCurrentEntitlements = true
storeManager.transactionsDidChange()
}
Always process unfinished transactions on app launch.
Users expect “Restore Purchases” to work, especially on new devices:
func restorePurchases() async -> Bool {
do {
try await AppStore.sync()
} catch {
Logger.error(error.localizedDescription)
return false
}
var restored: [TransactionRecord] = []
for await verificationResult in Transaction.all {
switch verificationResult {
case .verified(let transaction):
let renewalInfo = await fetchRenewalInfo(transaction)
restored.append(TransactionRecord(
transaction: transaction,
renewalInfo: renewalInfo
))
await transaction.finish()
case .unverified(_, let error):
Logger.error(error.localizedDescription)
}
}
storeManager.hasUpdatedCurrentEntitlements = true
storeManager.replaceTransactions(restored)
return true
}
AppStore.sync() triggers Sign in with Apple ID if needed. Then we iterate all transactions and rebuild our local state.
For fast paywall loading, fetch products early:
func fetchProducts() async {
guard storeManager.unpaid else { return }
do {
let products = try await StoreKit.Product.products(
for: StoreManager.Plan.allPaywall
)
storeManager.products = products
} catch {
Logger.error("fetchProducts: \(error.localizedDescription)")
}
}
Skip this for paid users - they won’t see the paywall anyway.
StoreManager is the single source of truth for purchase state:
import Foundation
import StoreKit
@MainActor
class StoreManager: ObservableObject {
static let shared = StoreManager()
private lazy var savedDataManager = SavedDataManager.shared
var products: [StoreKit.Product] = [] {
didSet { objectWillChange.send() }
}
private let maxTransactions = 9999
}
Organize product IDs as static properties for type safety:
enum Plan {
static let monthly = "hw_v4_monthly_single"
static let yearly = "hw_v4_yearly_single"
static let lifetime = "hw_v4_lifetime_single"
static let monthly_family = "hw_v4_monthly_family"
static let yearly_family = "hw_v4_yearly_family"
static let lifetime_family = "hw_v4_lifetime_family"
// Legacy plans for migration support
static let v3_monthly_1 = "hw_monthly_099"
static let v3_monthly_2 = "hw_1_month_auto"
static let v3_yearly_1 = "hw_1_year_auto"
static let v3_yearly_2 = "hw_1_year_auto_2"
static let v3_lifetime_1 = "hw_lifetime_499"
static let v3_lifetime_2 = "hw_lifetime_299"
static var allActive: [String] {
[
monthly, yearly, lifetime,
monthly_family, yearly_family, lifetime_family,
v3_monthly_1, v3_monthly_2, v3_yearly_1, v3_yearly_2,
v3_lifetime_1, v3_lifetime_2,
]
}
static var allLifetime: [String] {
[lifetime, lifetime_family, v3_lifetime_1, v3_lifetime_2]
}
static var paywallIndividual: [String] {
[monthly, yearly, lifetime]
}
static var paywallFamily: [String] {
[monthly_family, yearly_family, lifetime_family]
}
static var allPaywall: [String] {
paywallIndividual + paywallFamily
}
}
This approach makes it easy to add new products while maintaining backwards compatibility with legacy purchases.
The paid boolean is the primary entitlement check:
var paid: Bool {
get {
savedDataManager.store.bool(forKey: SavedDataManager.Keys.paid.rawValue)
}
set {
handlePaidChange(oldValue: paid, newValue: newValue)
savedDataManager.store.set(newValue, forKey: SavedDataManager.Keys.paid.rawValue)
objectWillChange.send()
}
}
var unpaid: Bool {
!paid
}
Use @ObservedObject and unpaid for feature gating in SwiftUI:
if storeManager.unpaid {
Button("Upgrade to Pro") { showPaywall = true }
}
When paid status changes, update app behavior:
func handlePaidChange(oldValue: Bool, newValue: Bool) {
switch (oldValue, newValue) {
case (false, true):
// User just subscribed
if settingsManager.showOnboarding {
settingsManager.apiSource = settingsManager.apiSourceDefault(paid: true)
syncService.sync()
}
case (true, false):
// Subscription expired or refunded
guard hasUpdatedCurrentEntitlements else {
// Don't downgrade until we've synced with App Store
return
}
settingsManager.apiSource = settingsManager.apiSourceDefault(paid: false)
savedDataManager.store.removeObject(forKey: SavedDataManager.Keys.radarLayer.rawValue)
await PushManager.shared.pushEnabledChanged()
syncService.sync()
default:
break
}
}
The hasUpdatedCurrentEntitlements guard prevents false downgrades before the initial sync completes.
Store transactions in UserDefaults with app groups for widget/watch access:
var transactions: [TransactionRecord] {
get {
guard let val = savedDataManager.store.data(
forKey: SavedDataManager.Keys.transactions.rawValue
) else { return [] }
return (try? JSONDecoder().decode(
[TransactionRecord].self,
from: val
)) ?? []
}
set {
let normalized = normalizedTransactions(newValue)
guard let val = try? JSONEncoder().encode(normalized) else { return }
savedDataManager.store.set(val, forKey: SavedDataManager.Keys.transactions.rawValue)
transactionsDidChange()
objectWillChange.send()
}
}
func process(transaction: Transaction,
renewalInfo: StoreKit.Product.SubscriptionInfo.RenewalInfo?) {
let record = TransactionRecord(transaction: transaction, renewalInfo: renewalInfo)
var updated = transactions.filter { $0.id != record.id }
updated.append(record)
transactions = updated
}
func transactionsDidChange() {
paid = activeTransactions.isNotEmpty
}
Derive all subscription state from the transaction array:
var activeTransactions: [TransactionRecord] {
transactions.filter { $0.active == true }
}
var inActiveTransactions: [TransactionRecord] {
transactions.filter { $0.active == false }
}
var paidLifetime: Bool {
activeTransactions.filter { $0.lifetime == true }.isNotEmpty
}
var expirationDate: Date? {
guard paidLifetime == false else { return nil }
return activeTransactions.compactMap { $0.expirationDate }.max()
}
var originalPurchaseDate: Date? {
return activeTransactions.compactMap { $0.originalPurchaseDate }.min()
}
var willAutoRenew: Bool {
guard paidLifetime == false else { return false }
return activeTransactions.filter { $0.willAutoRenew == true }.isNotEmpty
}
Show users exactly what’s happening with their subscription:
enum PaidStatus: String {
case lifetime = "Lifetime"
case subscribed = "Subscribed" // Active, will auto-renew
case cancelling = "Cancelling" // Active, won't renew
case cancelled = "Cancelled" // Expired
case unpaid = "Unpaid" // Never purchased
}
var paidStatus: PaidStatus {
if paidLifetime {
return .lifetime
} else if willAutoRenew {
return .subscribed
} else if paid {
return .cancelling
} else if hasPaid {
return .cancelled
} else {
return .unpaid
}
}
Store everything needed to determine entitlement without calling StoreKit:
import Foundation
import StoreKit
struct TransactionRecord: Codable, Identifiable, Equatable {
let environment: String?
let id: UInt64?
let originalID: UInt64?
let webOrderLineItemID: String?
let productID: String?
let productType: String?
let purchaseDate: Date?
let originalPurchaseDate: Date?
let expirationDate: Date?
let revocationDate: Date?
let revocationReason: Int?
let ownershipType: String?
let willAutoRenew: Bool?
let currency: String?
let price: Decimal?
init(transaction: Transaction,
renewalInfo: StoreKit.Product.SubscriptionInfo.RenewalInfo?) {
self.environment = transaction.environment.rawValue
self.id = transaction.id
self.originalID = transaction.originalID
self.webOrderLineItemID = transaction.webOrderLineItemID
self.productID = transaction.productID
self.productType = transaction.productType.rawValue
self.purchaseDate = transaction.purchaseDate
self.originalPurchaseDate = transaction.originalPurchaseDate
self.expirationDate = transaction.expirationDate
self.revocationDate = transaction.revocationDate
self.revocationReason = transaction.revocationReason?.rawValue
self.ownershipType = transaction.ownershipType.rawValue
self.willAutoRenew = renewalInfo?.willAutoRenew
self.currency = transaction.currency?.identifier
self.price = transaction.price
}
}
A transaction is active if:
var active: Bool {
guard StoreManager.Plan.allActive.contains(productID ?? "") else {
return false
}
guard revocationDate == nil else {
return false
}
if let expirationDate = expirationDate {
return Date() < expirationDate
}
return true // Lifetime purchase with no expiration
}
var inactive: Bool {
!active
}
var lifetime: Bool {
active && StoreManager.Plan.allLifetime.contains(productID ?? "")
}
Track why a transaction was revoked:
var revocationReasonString: String {
switch revocationReason {
case 0: return "Canceled"
case 1: return "Billing issue"
case 2: return "Upgrade/Downgrade"
case 3: return "Refunded"
case 4: return "Suspected fraud"
case 5: return "Pricing expired"
default: return "Unknown"
}
}
StoreKit 2 provides ProductView for purchasing UI. Wrap it with custom styles:
import SwiftUI
import StoreKit
@MainActor
struct PaywallView: View {
@ObservedObject private var storeManager = StoreManager.shared
@State private var showPlans: Bool = false
@State private var showRestoreNoPurchases: Bool = false
@State private var showRestoreSyncFailed: Bool = false
var body: some View {
VStack(spacing: 16) {
// Hero content...
Text("Try 1 week free, then \(storeManager.yearlyDisplayPrice ?? "...")/year")
ProductView(id: StoreManager.Plan.yearly)
.productViewStyle(TrialButton(buttonText: "Try 1 week free"))
HStack {
Text("See All Plans")
.onTapGesture { showPlans = true }
Text(" • ")
Button("Restore") {
Task {
let synced = await StoreService.shared.restorePurchases()
if !synced {
showRestoreSyncFailed = true
} else if storeManager.paid == false {
showRestoreNoPurchases = true
}
}
}
}
}
.alert("No active purchases found.", isPresented: $showRestoreNoPurchases) {
Button("Done", action: {})
}
.alert("Couldn't connect to App Store.", isPresented: $showRestoreSyncFailed) {
Button("Done", action: {})
}
.onChange(of: storeManager.paid) {
guard storeManager.paid == true else { return }
// Dismiss paywall on successful purchase
}
}
}
Create a styled purchase button:
struct TrialButton: ProductViewStyle {
var buttonText: LocalizedStringKey = "Try 1 week free"
func makeBody(configuration: Configuration) -> some View {
switch configuration.state {
case .loading:
PurpleButton(text: buttonText)
.redacted(reason: .placeholder)
case .success:
Button {
configuration.purchase()
} label: {
PurpleButton(text: buttonText)
}
.buttonStyle(.plain)
case .failure(let error):
let _ = Logger.error(error.localizedDescription)
PurpleButton(text: "Sorry, an error occurred.", error: true)
case .unavailable:
PurpleButton(text: "Sorry, an error occurred.", error: true)
@unknown default:
PurpleButton(text: "Sorry, an error occurred.", error: true)
}
}
}
Let users choose between plans:
@MainActor
struct PaywallPlansView: View {
@State private var selected: String = StoreManager.Plan.yearly
@State private var showFamilyPlans: Bool = false
var body: some View {
VStack {
HStack(spacing: 10) {
ForEach(plans, id: \.self) { plan in
ProductView(id: plan)
.productViewStyle(SelectablePlanStyle(selected: $selected))
.tag(plan)
}
}
Toggle("Add Family Sharing", isOn: $showFamilyPlans)
.onChange(of: showFamilyPlans) {
selected = showFamilyPlans
? StoreManager.Plan.yearly_family
: StoreManager.Plan.yearly
}
ProductView(id: selected)
.productViewStyle(TrialButton(buttonText: "Continue"))
}
}
private var plans: [String] {
showFamilyPlans
? StoreManager.Plan.paywallFamily
: StoreManager.Plan.paywallIndividual
}
}
struct SelectablePlanStyle: ProductViewStyle {
@Binding var selected: String
func makeBody(configuration: Configuration) -> some View {
switch configuration.state {
case .loading:
PlanCard(selected: $selected, id: "", title: "Loading", price: "...")
case .success(let product):
Button(action: { selected = product.id }) {
PlanCard(
selected: $selected,
id: product.id,
title: StoreManager.planTitle(product.id),
price: product.displayPrice,
badgeText: StoreManager.Plan.isYearly(product.id)
? "Best deal"
: nil
)
}
.buttonStyle(.plain)
case .failure, .unavailable:
EmptyView()
@unknown default:
EmptyView()
}
}
}
Show users their complete purchase history:
@MainActor
struct TransactionsView: View {
@ObservedObject private var storeManager = StoreManager.shared
@State private var selectedTransaction: TransactionRecord?
var body: some View {
List {
Section("Active (\(storeManager.activeTransactions.count))") {
ForEach(storeManager.activeTransactions.reversed(), id: \.id) { tx in
TransactionRowView(transaction: tx)
.onTapGesture { selectedTransaction = tx }
}
}
Section("Inactive (\(storeManager.inActiveTransactions.count))") {
ForEach(storeManager.inActiveTransactions.reversed(), id: \.id) { tx in
TransactionRowView(transaction: tx)
.onTapGesture { selectedTransaction = tx }
}
}
}
.navigationTitle("Purchase History")
.sheet(item: $selectedTransaction) { transaction in
TransactionDetailView(transaction: transaction)
}
}
}
struct TransactionDetailView: View {
let transaction: TransactionRecord
@State private var refundRequestSheetIsPresented = false
var body: some View {
List {
Section("Status") {
DetailRow(title: "Status",
value: transaction.active ? "Active" : "Inactive")
}
Section("Transaction Details") {
DetailRow(title: "Product",
value: StoreManager.planTitle(transaction.productID))
DetailRow(title: "Type", value: transaction.productType)
DetailRow(title: "ID", value: transaction.id?.description)
DetailRow(title: "Environment", value: transaction.environment)
DetailRow(title: "Price", value: transaction.formattedPrice)
DetailRow(title: "Will Auto Renew",
value: transaction.willAutoRenew?.description)
}
Section("Dates") {
DetailRow(title: "Purchase Date",
value: transaction.purchaseDate?.formatted())
if let expiration = transaction.expirationDate {
DetailRow(title: "Expiration", value: expiration.formatted())
}
if let revocation = transaction.revocationDate {
DetailRow(title: "Revoked", value: revocation.formatted())
DetailRow(title: "Reason",
value: transaction.revocationReasonString)
}
}
Section("Manage") {
Button("Request Refund") {
refundRequestSheetIsPresented = true
}
}
}
.refundRequestSheet(
for: transaction.id ?? 0,
isPresented: $refundRequestSheetIsPresented
)
}
}
Activate StoreService during app launch:
@main
struct HelloWeatherApp: App {
init() {
AppMonitor.activate() // Calls StoreService.shared.activate()
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
Finish transactions immediately - Call transaction.finish() right after verification. The App Store holds unfinished transactions until you do.
Guard against false downgrades - Don’t revoke access until hasUpdatedCurrentEntitlements is true. On cold launch, the persisted paid flag might be stale.
Monitor both streams - Transaction.updates catches purchases, but SubscriptionInfo.Status.updates catches renewal state changes.
Persist everything - Store the full TransactionRecord, not just the product ID. You need expiration dates, revocation info, and renewal state for proper UI.
Pre-fetch products - Calling Product.products(for:) early avoids paywall loading delays.
Use app groups - Store transactions in shared UserDefaults so widgets and watch apps can check entitlements.
Handle verification failures gracefully - Log them, but don’t crash. Could be a jailbroken device or network corruption.
Test sandbox thoroughly - Use StoreKit Configuration files for unit tests, and test account sandboxes for integration testing.
Prompt: “review ~/Code/helloweather/ios and create a post about StoreKit 2 with extensive examples, this one a bit longer than others with more clear code examples. don’t hide anything, since this is standard functionality I want to share. review this implementation guide and implementation example for some work we did a few months back that may be a great starting point. create a pr and save this prompt as always, but trim the following markdown I’m pasting since it’d be duplicative…”
Generated by Claude using the blog-post-generator skill. Based on production code from Hello Weather’s StoreKit 2 implementation handling subscriptions, lifetime purchases, and family sharing.
]]>Crash reporting SDKs want to help you. They’ll collect performance metrics, user sessions, network requests, breadcrumbs, and interaction traces. Most of this ships enabled by default.
For a privacy-focused app, this is a problem. You want crash reports. You don’t want to accidentally ship a user analytics platform.
Crashes only. Nothing else.
Collect:
Don’t collect:
Crash reporting SDKs evolve. New features get added. Some get enabled by default. Your carefully configured privacy settings can break with a single dependency update.
The trap: Disabling high-level features doesn’t always disable underlying collection mechanisms.
For example, turning off enableAutoPerformanceTracing might not disable enableDataSwizzling - the infrastructure that makes performance tracing possible is still running, just not reporting.
Before updating your crash reporting SDK:
Look for phrases like “enabled by default”, “now automatically”, or “improved telemetry”. These are red flags that require investigation.
Don’t trust that disabling a feature disables its infrastructure. Search the SDK source for:
If the mechanism is active, data is being collected somewhere - even if it’s not being sent yet.
Scrutinize or explicitly disable anything involving:
If you’re uncertain whether a feature collects user data, disable it. You can always enable it later if needed. You can’t un-collect data that’s already been sent.
Here’s how we configure Sentry for iOS - the same principles apply to any crash reporting SDK:
SentrySDK.start { options in
options.dsn = "your-dsn"
// Core crash reporting only
options.enableCrashHandler = true
// Disable everything else explicitly
options.enableAutoPerformanceTracing = false
options.enableUIViewControllerTracing = false
options.enableNetworkTracking = false
options.enableFileIOTracing = false
options.enableCoreDataTracing = false
options.enableSwizzling = false // Critical: disables the mechanism
options.enableAutoBreadcrumbTracking = false
options.enableNetworkBreadcrumbs = false
options.attachScreenshot = false
options.attachViewHierarchy = false
options.enableMetricKit = false
options.enableTimeToFullDisplayTracing = false
// No session tracking
options.enableAutoSessionTracking = false
options.sessionTrackingIntervalMillis = 0
}
The key insight: we disable enableSwizzling entirely. This is the mechanism that powers many features. Disabling it at the infrastructure level is more reliable than disabling individual features that depend on it.
Configuration isn’t enough. Verify that nothing extra ships:
If anything unexpected shows up, investigate which setting is responsible and disable it.
If your app runs on multiple platforms (iOS, watchOS, widgets), ensure your crash reporting configuration works everywhere:
With this approach:
Prompt: “let’s write (one or more) posts about the skills we have in helloweather web and ios. I’m thinking perhaps one about sentry in the ios repo, where we document how we want to maintain privacy and beware of new settings that might be enabled by default, to ensure we only do the minimal crash reporting and respect privacy.”
Generated by Claude (Opus 4.5) using the blog-post-generator skill. Based on the iOS Sentry skill from helloweather/ios, generalized to apply to any crash reporting SDK.
]]>