菜单
Apply when reviewing or writing code that touches the IMAP sync flow — anything in internal/client, internal/app/sync.go, internal/app/worker.go, internal/app/show.go. Encodes the non-obvious correctness traps specific to IMAP and to this tool's plan-confirm-execute model.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Apply when auditing test coverage on changed packages. Used by the `tester` agent. Encodes the project's stance: branch and invariant coverage matter more than total %, deliberate exclusions must be recorded with reasoning.
Apply when verifying that comments and docs match the current code state. Used by the `tech-writer` agent. Encodes the project's WHY-only comment rule and the doc surfaces that must stay in sync (CLAUDE.md, README.md, config.example.{json,yaml}).
Apply when reviewing Go code in this repo for idiom, allocation cost, struct layout, error wrapping, concurrency safety. Triggered by review-style requests on `.go` files, by the `architect` agent when forming verdicts, and by the `developer` agent self-checking before reporting. Loads the project's Go-style rule set.
Apply when auditing changes for security in this repo. Used by the `security` agent. Encodes the threat model (operator trusted, IMAP servers + network partially trusted, no listening sockets) and the standing checklist.
| name | imap-sync-correctness |
| description | Apply when reviewing or writing code that touches the IMAP sync flow — anything in internal/client, internal/app/sync.go, internal/app/worker.go, internal/app/show.go. Encodes the non-obvious correctness traps specific to IMAP and to this tool's plan-confirm-execute model. |
This is a sync tool. The single most important property is "running it again does the right thing". Every rule below exists to protect that property.
FetchRFC822 sets \Seen. Use BODY.PEEK[...] everywhere. A sync tool must not mutate source state. If you see FetchRFC822 anywhere outside a test, that's a bug.safeCall. Direct c.Client.<method> calls skip the reconnect+classify+cancel pipeline. New IMAP ops always go through safeCall.selectIfNeeded. Calling cli.Select directly costs a round-trip per batch and races with reconnect. Always use selectIfNeeded.uidFetchBatchSize = 500 exists because some servers reject longer arg lists with "Too long argument". Do not unbatch.AppendMessage consumes the message body once. A transient mid-APPEND error cannot be retried inside this run — the literal is gone. The diff catches it on the next run. Do not "fix" this by adding io.ReadAll — that doubles peak RAM.reconnectInterval = 10s, maxReconnectAttempts = 5, throttledBackoff = 5m. Don't weaken these "for testing" without reverting before commit.LIST "" "*" per Client. Invalidated only on CreateMailbox. Re-LISTing on every check is a regression.atomic.Pointer fields. c.pw, c.tracker. Always read via c.progressWriter() / c.progressTracker(). Direct field access is a data race.Client per worker, for the whole sync. Do not reconnect per plan.sleepCtx for all reconnect-path sleeps. Plain time.Sleep makes Ctrl-C hang for up to 5 minutes.defer c.withCancel(ctx)() on every long-running public Client method. Plus ctx.Err() checks after each blocking step. Otherwise Ctrl-C only takes effect at the next IMAP round-trip.internal/app/sync.go is structured as:
A streaming "fetch one, append one, repeat" model would also work but it would lose the confirmation step and make the operation impossible to dry-run. Any refactor that collapses steps 3 and 6 is a regression.
There is no UID bookkeeping. There is no resume file. Re-running on a partially completed sync re-diffs and continues. If you find yourself wanting to add a state store, stop and explain the use case to the architect — there is probably a way to express it as part of the diff instead.