Build failures become manageable when you preserve the first relevant diagnostic and the exact command. Repeatedly changing unrelated Swift files destroys the context needed to explain the failure.

Reproduce command → Identify first error → Patch one cause → Repeat same check
  1. 1Reproduce command
  2. 2Identify first error
  3. 3Patch one cause
  4. 4Repeat same check

Work through the example

Classify a failure as environment, project configuration, compiler or behavior before suggesting a fix. Record a bounded retry limit.

Start with a disposable branch and synthetic data. Write the expected outcome before changing the implementation, then keep the first failing result. This prevents a later repair from quietly redefining the task. The procedure below is grounded in the repository reference; its examples must still be checked against your project and installed toolchain.

Implementation reference

The following focused section is adapted from the maintained project guide. It preserves the source’s examples and limitations.

Evidence and resume

  • Artifacts must use canonical relative paths under .ios-agent/evidence/. Symlink evidence paths are rejected. Checks must create fresh, nonempty artifacts; demo verification additionally validates PNG signatures.
  • State, logs and evidence are stored in .ios-agent/. Add that directory to your project's .gitignore; logs may contain source code, local paths or command output. The loop does not publish them or copy credentials. Claude receives the brief, configuration and failing log excerpts through your local authenticated CLI.
  • Successful checks are reused only when source fingerprints and saved evidence/log hashes match. Source changes invalidate cached results. Generated directories such as .build, build, DerivedData, node_modules, .git, .ios-agent and Xcode user/workspace metadata are excluded; do not keep implementation source there.
  • Interruptions preserve progress and terminate active process groups on macOS/Linux. Resume rechecks interrupted work. Windows process cleanup is limited to the direct child; iOS simulator verification requires macOS.
  • Frozen verification files cannot change mid-run. To intentionally revise the acceptance contract, archive .ios-agent/loop and initialize a new run. Do not edit saved results to claim completion.
  • Completion means every configured check passed with retained artifacts. Screenshots need human visual inspection; they are not automatic proof of visual quality, full accessibility or App Store readiness.

Acceptance and failure review

Checkpoint What to inspect If it does not match
Reproduce command Confirm the input and environment Preserve the failure and return to this step
Identify first error Inspect the intermediate artifact Preserve the failure and return to this step
Patch one cause Run the focused check Preserve the failure and return to this step
Repeat same check Record the observed result Preserve the failure and return to this step

Ask the agent to explain the smallest change that resolves the observed mismatch. Keep unrelated refactors out of the repair. A change that makes a warning disappear is not enough if the behavior or ownership contract has changed. Re-run the same acceptance check so the before and after results are comparable.

Evidence and limits

The diagnostic exercises are examples, not a measured ranking of the ten most common errors.

This is an educational guide. Its presence in the series does not certify a completed client-specific lab. The series evidence record separates executed checks from exercises and blocked environments.

Inspect the source used in this lesson.

What to do next

Next: Review Swift 6 settings and actor isolation before changing agent-generated code