Greetings, traveler!
The CI build was green yesterday. This morning, Xcode cannot resolve one of the project’s Swift packages. The application code has not changed, and the error mentions a package version that appears to exist.
An AI agent can start trying fixes immediately: clear DerivedData, reset package caches, delete Package.resolved, and run the build again. If the next attempt succeeds, the agent may report that the problem is fixed. It may even be right. But if several things changed at once, the team still does not know which action mattered or whether another machine will fail tomorrow.
Debugging is a different task from implementing a feature. Before changing the system, the agent needs to establish what failed, what evidence is available, and which explanation can be tested with the least disruption. This is especially useful with AI because an agent can generate plausible fixes much faster than a developer can evaluate their consequences.
The following package-resolution incident is hypothetical. The commands and results illustrate an investigation; they are not a report of an actual project or a guarantee that every Xcode version will produce the same error.
Start with an observable failure
A useful bug report describes behavior that another person can check. “Swift Package Manager is broken” leaves too many possibilities open. A more useful starting point is:
The CI job fails while resolving package dependencies for
App.xcworkspace. The same commit resolved successfully in the previous release pipeline. A developer with an existing checkout can still build locally.
That description already narrows the investigation. The failure occurs before compilation, and the difference between environments may matter. It does not yet identify a cause: credentials, a missing Git revision, an incompatible manifest, a changed tag, a different Xcode version, and network access could all produce resolution problems.
Ask the agent to capture the exact failing command and the first relevant error, including the surrounding output. Record the commit, workspace, selected Xcode version, and whether the environment has an existing package checkout. If the failure is intermittent, record how often it occurs and under what conditions. A clean reproduction is useful, but an incident may initially be reproducible only on CI. In that case, preserving its logs and comparing successful and failed runs is still progress.
Logs can contain private repository URLs, usernames, or credentials. Redact them before sharing outside the environment, and avoid logging tokens or complete environment variables.
Define the investigation before asking for a fix
A broad request such as “fix the build” encourages a sequence of speculative changes. A better prompt sets a boundary and asks for evidence:
Investigate the package-resolution failure in CI.
First, capture the failing command, the relevant error, the current commit,
and the Xcode version. Compare the failed run with the last successful run.
List plausible causes and a check for each one.
Do not delete caches, modify Package.resolved, update dependencies, or change
remote Git tags during the investigation. Explain any proposed change and
what result would support or contradict the hypothesis.
Report observations separately from assumptions. If the failure cannot be
reproduced, say what evidence is missing.
This request does not require the agent to follow a rigid procedure for every typo or obvious compile error. It is appropriate when the cause is uncertain and the next action might discard useful state or affect other developers. For a production incident, the team may need to restore service first. A rollback or other mitigation can be the right immediate action, provided it is recorded as a mitigation and investigated afterwards.
Reproduce without erasing the evidence
Start from the failed job’s actual invocation. A typical Xcode workspace might resolve packages with:
xcodebuild -resolvePackageDependencies \
-workspace App.xcworkspace \
-scheme App
The workspace, scheme, selected toolchain, authentication setup, and other options should match the failing environment. Running a different command can be informative, but its result does not necessarily reproduce the CI failure.
Capture the command’s exit status as well as its output. When piping to tee in Bash, enable pipefail so the pipeline does not report success merely because the log was written successfully. The conditional also captures failures when the surrounding script uses set -e:
set -o pipefail
if xcodebuild -resolvePackageDependencies \
-workspace App.xcworkspace \
-scheme App 2>&1 | tee /tmp/package-resolution.log; then
status=0
else
status=$?
fi
printf 'Resolution pipeline exit status: %s\n' "$status"
The pipeline status also reflects a failure of tee, so check the log-writing error if the output cannot be saved. In a CI script, propagate the recorded status when appropriate, for example with exit "$status".
For comparison, record xcodebuild -version and xcode-select -p on both machines. Run them in the same environment as the failing command: a job can override the selected developer directory with DEVELOPER_DIR. Check whether the job sets that variable and inspect its value where appropriate. Also inspect the CI configuration for custom package directories, mirrors, and resolution flags. Look for the first meaningful failure in the log rather than treating the final “build failed” message as the diagnosis.
Existing checkouts and caches may explain why one environment succeeds while another fails. A fresh checkout on a disposable runner or a separate local clone can help test that difference. A new clone on the same machine may still share SwiftPM caches, package checkouts, mirrors, credentials, and other configuration. To investigate their effect, identify those locations and compare or isolate them without destroying the original state. Keep the app commit and toolchain the same where possible, and note any remaining differences in credentials, network, and package configuration. A clean checkout is an experiment, not proof that the cache is defective.
Turn possibilities into testable hypotheses
A list of explanations becomes useful when each entry predicts an observable result. For the hypothetical failure, the agent might write:
| Hypothesis | Evidence to look for | What the result would mean |
|---|---|---|
| CI cannot authenticate to the package repository. | The same CI identity cannot read the remote and the log shows an authentication failure. | Investigate credentials or repository access. A successful read makes this less likely for that repository. |
| A dependency constraint cannot be satisfied. | Resolution reports conflicting requirements, or manifests impose incompatible ranges. | Inspect both direct and transitive requirements before choosing a version change. |
| The recorded Git revision is unavailable to a fresh clone. | Package.resolved identifies a revision that cannot be checked out in a fresh repository fetched with the CI identity. | Investigate the revision’s history and availability. It does not by itself establish why the revision disappeared. |
| The version tag now points to a different commit. | The remote tag’s commit differs from the revision recorded for that version. | A tag/revision mismatch exists. Establish its history and test whether it causes the observed error. |
| The toolchain differs. | The failing and successful runs use different Xcode versions. | Test with the same version before attributing the failure to the toolchain. |
The best next check is usually the one that distinguishes several possibilities without changing project state. A hypothesis should also be allowed to fail. If the test contradicts it, the agent should record that result and move on rather than reinterpret it as confirmation.
Follow the package from the app to Git
Assume the failed log names a package called TelemetryKit and a particular revision. First locate the Package.resolved actually used by the workspace. An Xcode project, a shared workspace, and standalone Swift packages can each have their own resolved file. The exact location depends on the project structure, so inspect the workspace and the build invocation instead of assuming that every file named Package.resolved is authoritative.
A quick inventory helps:
find . -name Package.resolved -print
Inspect the relevant file and its history. In the example below, set RESOLVED_FILE to the path used by the workspace and LAST_GOOD_COMMIT to the commit from the successful run:
cat "$RESOLVED_FILE"
git log --oneline -- "$RESOLVED_FILE"
git diff "$LAST_GOOD_COMMIT" HEAD -- "$RESOLVED_FILE"
A resolved file records selected dependency information, including versions and revisions where applicable. It is an important clue, but it is only part of the resolution: the app’s dependency declarations, transitive package manifests, remote references, and toolchain also matter. A changed file is evidence of a change, not proof that the change caused the failure.
Next, inspect the remote tag. Set PACKAGE_URL to the repository URL used by the failing environment. This example looks for a 1.4.0 tag:
git ls-remote --tags "$PACKAGE_URL" \
'refs/tags/1.4.0' 'refs/tags/1.4.0^{}'
A lightweight tag points directly to an object, normally a commit. Compare that object’s hash with the recorded revision. For an annotated tag, Git can show both the tag object and a peeled ^{} entry. Compare the commit referred to by the peeled entry with the recorded revision; do not mistake the annotated tag object’s hash for the commit hash. If there is no matching tag, check the name, remote URL, and permissions before drawing a conclusion.
Suppose the resolved file records commit A for version 1.4.0, while the remote tag resolves to commit B. A fresh clone cannot check out A, but the existing local checkout still has it. A failed checkout establishes that A is missing from that clone; the server may still have the object without advertising a reference that causes a normal clone to fetch it. Whether a client can request the object directly depends on server configuration and permissions. These observations suggest a possible explanation for the environment difference, but they do not establish when a tag moved or who moved it. Check the repository host’s audit records, release process, or package maintainers if those records are available.
A controlled check can strengthen the diagnosis. In an isolated copy, test whether the exact failing revision is available with the CI identity, using the same repository configuration. If a temporary version choice is needed to compare outcomes, make it only in the disposable copy and record the resulting diff. If the original failure disappears when the unavailable revision is no longer requested, that supports the explanation. It does not prove that every possible failure in the project has the same cause.
Choose a correction that fits the evidence
If the team confirms that a published tag was moved and the previous commit is no longer available to fresh consumers, there is an important release-management decision. Coordinate with the package maintainers before changing a shared remote tag. Depending on the repository’s policy and the availability of the original commit, the team might restore the original tag or publish the intended code under a new version. Moving a shared tag again can affect consumers that already resolved the newer commit.
On the application side, update the dependency and Package.resolved through the project’s normal workflow when a valid version is available. Review the resulting diff, including any other dependency changes. Deleting the resolved file can cause a broader re-resolution, so it should not be an automatic first step. Likewise, clearing a cache may be useful when corruption is actually supported by evidence, but it can also remove the state needed to understand the incident.
The correction depends on what the investigation finds. If the logs instead show an authentication failure, changing a package version is unlikely to address the underlying access problem. If requirements conflict, the relevant manifests need attention. The same visible failure, “package resolution failed,” can have several unrelated causes.
For example, suppose the hypothetical investigation confirms that A is no longer available through the CI fetch, and the package maintainers confirm that the tag was moved. They publish the intended code as 1.4.1. In a disposable copy of the app, the team updates the dependency through its normal workflow, reviews the resulting Package.resolved diff, and verifies that the affected package resolves to the intended revision. The team then checks the change in a fresh CI environment using the same Xcode and access configuration as the failed job. A successful resolution and build there would support the correction; the report should still record any tests that were not run. These are illustrative results, not an actual CI run.
Use diagnostic logging to trace a runtime failure
The package investigation uses Git state and build logs. A runtime defect calls for different observations, but the same approach to testing explanations applies. Consider a screen that occasionally displays an older result after a user changes a filter. A plausible explanation is that two requests overlap and the earlier request finishes last. Another possibility is that the wrong filter reaches the networking layer.
Add temporary, privacy-safe logs at the boundaries: when the filter changes, when a request starts, and when its result is applied. Give each request an identifier and include the filter value only if it is safe to log. Then reproduce the sequence and compare the request order with the application order. Avoid logging response bodies or personal data merely because they are available.
If the logs show that request A starts first, request B starts second, B updates the screen, and A subsequently replaces it, the ordering supports the stale-response hypothesis. Inspect the ownership and cancellation behavior before selecting a fix. Cancellation alone may not be sufficient if the underlying operation does not stop promptly; the state update may also need to verify that the result still belongs to the current request.
A deterministic test can model this ordering by controlling when each dependency completes. Release B first, then A, and assert that the screen retains B’s result. This is more informative than adding a fixed sleep and hoping the scheduler produces the desired order. Remove or reduce temporary diagnostics once they have served their purpose, unless they provide ongoing operational value.
Verify the fix at the boundary where it failed
For the package example, a successful local build with an existing checkout is a weak final check if the original failure affected fresh CI runners. Verify the corrected dependency state in a fresh environment with the intended Xcode version, repository access, and CI configuration. Then run the relevant build and tests. If the original failure depended on a particular runner or credential, repeat the check there when possible.
A useful report includes:
- The original symptom and the conditions under which it appeared.
- The observations that support the diagnosis, including what remains uncertain.
- The change made and why it addresses those observations.
- The commands or jobs run after the change, their outcome, and the commit or state tested.
- Checks that could not be run and any remaining risk.
For an application defect, preserve a regression test when a meaningful automated reproduction is practical. For an external repository or CI configuration failure, the regression check may instead be a pipeline step that resolves dependencies from a clean environment. Such a step catches some availability and configuration problems, though it cannot guarantee that a remote repository will remain available forever.
Know when to stop an automated repair loop
Retries are useful for transient network failures, but repeated attempts should be bounded and their purpose should be clear. If the agent sees the same error after several attempts with no new information, another identical run is unlikely to explain the cause. Stop and reassess the evidence.
Pause automatic changes when a proposed action would alter shared tags, credentials, production data, or dependencies outside the task’s scope. Stop as well when each attempted fix introduces another unexplained failure or when the agent can no longer distinguish its own changes from the original problem. Preserve the diff and logs, then ask an engineer to decide how to proceed.
For an intermittent issue, stopping does not require a complete diagnosis. The outcome may be a documented limitation, additional instrumentation, or a plan to collect evidence on the next occurrence. A team can also run independent investigations for a difficult problem, provided each investigator starts from the same facts and tests its own explanation. Agreement between agents is useful for organizing the discussion, but observations and reproducible checks determine how much confidence the team should place in it.
It might be interesting:
- AI-Assisted Architecture Migration: Keeping Large Refactors Under Control
- AI Code Review: Finding Defects Without Creating More Work
- Deterministic Testing for iOS: Reproducing the Failures That Matter
- Visual Verification: Giving AI Agents a Way to Check iOS Interfaces
- Evidence-Driven Development: How to Verify AI Agent Changes
