What the agent does
Go moved everything in io/ioutil to the os and io packages in 1.16 and later marked the package deprecated. Most of the move is a rename, and the agent starts by sorting the calls into those that are and those that are not. In a program like perkeep/gphotos-cdp, which downloads a Google Photos library by driving Chrome, main.go imports io/ioutil on line 27 and calls it five times: ioutil.ReadFile in getLastDone, ioutil.TempDir in NewSession, ioutil.WriteFile in markDone, and ioutil.ReadDir twice, in cleanDlDir and in the loop inside download that waits for a file to finish.
Three of those are renames with the same signature: os.ReadFile, os.WriteFile and os.MkdirTemp. Before making them the agent reads go.mod, because the new names do not exist in every release. This module says go 1.12, four releases before the functions arrived. So the first change is to the go directive, and the agent raises it to the lowest version that has the replacements, or to the version your CI builds with if that is higher, and says which and why. The same line explains why no linter complained: staticcheck holds back a deprecation finding until the module's declared Go version reaches the release it dates the deprecation from. With go 1.12 it prints nothing for this file, and it stays silent at 1.16 as well. From a directive of 1.19 it reports io/ioutil has been deprecated since Go 1.19 under check SA1019.
ReadDir is the call that is not a rename. ioutil.ReadDir returns []os.FileInfo; os.ReadDir returns []os.DirEntry, a lighter value that knows the name and whether the entry is a directory but has not looked up size or modification time. In cleanDlDir the loop only calls IsDir() and Name(), so the swap compiles and behaves the same. In download it does not compile: the loop appends entries to a []os.FileInfo and later reads fileEntries[0].Size() to tell whether a download is still growing, and the compiler rejects the append because DirEntry has no ModTime. The fix is to call Info() on the entry, which returns the FileInfo and an error.
That error is where the behaviour can change, and the agent writes the handling deliberately. The loop is watching a directory in which Chrome renames a .crdownload file to its final name when the transfer completes. An entry can therefore vanish between the directory listing and the Info() call, and Info() then returns an error for which errors.Is(err, fs.ErrNotExist) is true. The old function looked up each file as part of the listing and gave the caller no error for an entry that disappeared in between. If the port returns every Info() error, a download that finishes at the wrong instant becomes a failed run. The agent treats a not-exist error as an entry to skip, so the loop comes round again and sees the renamed file, and returns any other error as before. It then runs go build ./... and go vet ./... and reports what vet already says about this file, an unreachable statement on line 242, without touching it.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Replace the deprecated io/ioutil package in this Go module with its replacements in os and io. Read go.mod first: the replacements need Go 1.16 (os.ReadFile, os.WriteFile, os.ReadDir, os.MkdirTemp, os.CreateTemp, io.ReadAll, io.Discard, io.NopCloser). If the go directive is older, raise it to the lowest version that works, or to the version the CI workflow or Dockerfile builds with if one is pinned, run go mod tidy, and explain the choice and any change it caused in go.mod and go.sum. List every ioutil call with its file, line and enclosing function. Apply the same-signature renames. For each ioutil.ReadDir, read how the result is used: if the code needs Size, Mode or ModTime, call Info() on the DirEntry and handle its error; when the directory can change while it is being read (downloads, temp files, logs), treat an fs.ErrNotExist from Info() as an entry to skip and say so in a comment, and return any other error. Note that os.ReadDir sorts by filename as ioutil.ReadDir did. Remove the import. Do not refactor anything else. Run gofmt, go build ./..., go vet ./... and the tests if there are any; if there are none, say so. Install staticcheck and run check SA1019 before and after; if it reports nothing before your change, say whether the go directive is the reason. Report other findings without fixing them. Open a pull request with the list of calls, the build and vet output, and the staticcheck output before and after.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that changes main.go and go.mod, and go.sum if tidying under the new directive alters it. The description has a table of the five calls: function, old call, new call, and whether the signature changed. Four rows say no. The row for the loop in download links to the new Info() block and explains the skip on a missing file in two sentences. Below it are the go build and go vet results and what staticcheck said before and after, with a note when a low go directive is the reason it said nothing.
A reviewer spends their time on that one row. They check that the skip applies only to a not-exist error and that the rest of the loop, the deadline that moves while the file size grows and the .crdownload suffix test, is unchanged. They also decide whether the new go directive suits them, since it sets the minimum toolchain for anyone who builds the module. The description says this repository has no test files, so the evidence is a clean build and vet, not a passing suite, and it does not pretend otherwise.
Run it on every Linear issue labelled tech-debt
Deprecation cleanups tend to live in a tracker as small tickets nobody picks up. Connect Linear under Settings → Connections, then add an automation on the Project with a linear trigger on linear.issue.labeled, your label, and the prompt above. The issue that gained the label is added after the prompt as event text. It fills in nothing in the prompt, so write the prompt to stand on its own, as this one does.
The trigger fires when a member of your Rush org applies the label, and each labelled issue starts one run. For a group of services, one automation per Project with the same prompt gives one pull request per module, and the automation's max runs per hour caps a bulk relabel.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
This is a cleanup that looks too small to plan and is therefore done by search and replace, which is how the Info() error ends up returned, ignored or dropped with a blank identifier. Getting it right means reading what each directory listing is used for and what else is writing to that directory. The agent reads the surrounding function for every call, and it compiles after each step in a sandbox with a current Go toolchain, so the type error that marks the interesting call is in the run's record and not something a reviewer has to rediscover.
It also answers the toolchain question with evidence. Raising a go directive on a hunch can change go.mod more than expected. The agent runs go mod tidy under the version it proposes and shows the resulting diff, so the cost of the directive change is visible in the same pull request as the benefit.
Frequently asked questions
Is io/ioutil going to be removed?
No. Go's compatibility promise keeps the package in the standard library, and since 1.16 its functions are thin wrappers around the ones in os and io. The reasons to move are that linters flag it once your module declares a recent Go version, and that os.ReadDir avoids a file lookup per entry when you only need names.
What is the difference between ioutil.ReadDir and os.ReadDir?
The return type. ioutil.ReadDir gives []fs.FileInfo, with size and times already fetched for every entry. os.ReadDir gives []fs.DirEntry, which has Name(), IsDir() and Type(), and an Info() method that fetches the rest on request and can fail. Both return entries sorted by filename.
Why did my linter not warn about ioutil?
Check the go line in go.mod. staticcheck holds back a deprecation warning when the declared language version is older than the release that deprecated the API, because the module may still need to build with an older toolchain. For io/ioutil that release is 1.19, so a directive of 1.16 is enough to use the replacements and still too low for the warning.
Does it update vendored or generated code?
No. Files under vendor/ belong to your dependencies and change when you upgrade them, and generated files are rewritten by their generator. The agent lists any ioutil imports it finds there, names the dependency or generator responsible, and leaves the files alone.
More jobs like this: Turn a Linear label into a PR
- Migrate From lib/pq to pgx in a Go API (lib/pq)
- Migrate From Logrus to log/slog in a Go CLI (Logrus)
- Migrate mkdirp to fs.mkdir with recursive: true (mkdirp)
- Replace Moment.js With Day.js in an Express API (Moment.js)
- Replace pytz With zoneinfo in a Python Scraper (pytz)
- Migrate From querystring to URLSearchParams in a Node.js API Client (querystring)