A docs sweep that found two more stale claims than expected

This was a low-priority cleanup issue from an earlier review spike - six specific docs and config drift points to fix. What made it interesting was that actually verifying each one before touching anything turned up two more that weren’t on the list at all.

Problem

Six known items: the README claiming CI runs “on every push” when it’s actually tag/manual-only now; the docs saying “iOS 17+” when the real deployment target is 17.6; the README still reading as if the app were named “Discoverer” after the rebrand to “Deep Cut Atlas”; a directory missing from the docs’ file tree; a SwiftLint config excluding a file that had been deleted; and a doc comment describing an implementation that had since changed.

Why this approach

My working rule for any issue is to verify against the actual repo state before planning, not just implement what the ticket says. For a docs issue that’s especially direct: every claim in the ticket IS a claim about doc and code state, so I can check every single one before writing a plan, rather than after.

That verification pass is what surfaced the extra two. Reading the actual fetchLibraryAlbumKeys() implementation to fix its doc comment, I noticed the docs’ example xcodebuild commands were both missing the -project flag - and confirmed by literally running them that they fail from the repo root as written (“does not contain an Xcode project”). And while double-checking those same commands worked with a real destination, I found that “iPhone 16 Pro” - the simulator name hardcoded into both docs - doesn’t exist on this machine anymore. The available simulators have moved on to the iPhone 17 generation.

Implementation

Also worth flagging: before touching the “align naming” item, I checked my notes from the original rebrand first instead of just replacing “Discoverer” with “Deep Cut Atlas” everywhere. There was already a recorded decision there - I’d explicitly declined renaming the Xcode target, scheme, and repo, since that’s risky GUI surgery for zero user-facing benefit. So the fix was narrower than a global find-replace: fix the prose describing the app to a person reading the README to say “Deep Cut Atlas,” while leaving every technical reference (the .xcodeproj path, the scheme name in build commands, the clone URL) as “Discoverer.”

Everything else was mechanical once verified: fix the CI trigger claim, bump the iOS version string, add the missing directory entry and a one-line hooks-setup note (the docs had zero mention that a fresh clone needs git config core.hooksPath .githooks or it silently skips linting), drop the dead SwiftLint exclusion, add an opt-in rule for orphaned Task errors, and fix the doc comment to describe the actual off-main Task.detached implementation instead of the older chunked-on-main one.

Gotchas

The stale simulator name is the one I’d call out as a recurring failure mode worth naming: any doc or script that hardcodes a specific iPhone model name will eventually go stale, because Apple ships new iPhone generations and old simulator runtimes age out of Xcode. This repo’s own CI workflow already solved this the right way - it resolves an available iPhone at runtime with xcrun simctl list devices available instead of hardcoding a name. The README examples are meant to be simple copy-paste snippets for a human, so I didn’t rebuild them into the same dynamic-resolution shell logic, but I did swap the hardcoded name to whatever’s actually available today, fully expecting it’ll need the same treatment again in a year or two.

Results

SwiftLint strict passed clean with the new opt-in rule (zero fire-and-forget Task blocks dropping errors anywhere in the codebase, which is itself a small vote of confidence in the “async/await everywhere” convention actually being followed). Full suite stayed green at 163/163 - expected, since none of this touched app code paths. And I didn’t just trust the corrected example commands looked right; I actually ran the build with the new -project flag and the new simulator name and confirmed it built successfully, which is exactly how I found the stale simulator name in the first place.

Small issue, but a good reminder that “fix what the ticket says” and “fix what’s actually true” aren’t always the same list, and the gap between them is usually only visible if you check.