Removing duplication in swift-claw
Duplication means one rule stated twice: the same domain knowledge, not similar-looking lines.
A merge must preserve behavior on every supported platform (macOS and Linux CI). A difference
you cannot prove is accidental stays separate.
1. Before any edit
- Read
Package.swift (target edges), docs/ARCHITECTURE.md §3.1 (owners), docs/TESTING.md.
- Run
swift test once and record the actual result. The final run is compared to this one.
- Create a ledger file in the scratchpad. Every candidate group gets one row (§3).
2. Two passes
Pass 1, per target. Cover each directory in Sources/ and Tests/. Look for repeated
private helpers, repeated literals that name one thing, and the same guard in several files.
Pass 2, across targets, by rule. Search each category in all of Sources/:
| Rule |
Seeds |
| Validation |
guard .* else { throw, isEmpty, "..", character-set checks |
| Retry, timeouts |
retry, backoff, sleep(for:, deadline, duration(to: |
| Paths |
resolvingSymlinksInPath, standardizedFileURL, realpath, hasPrefix( |
| Config, env |
environment[, CLAW_, default values parsed from strings |
| Serialization |
JSONEncoder(), JSONDecoder(), outputFormatting, CanonicalJSON |
| Errors |
catch, StoreError, classifyError, user-facing error copy |
| Resources |
FileHandle, open(, close(, defer, O_NOFOLLOW |
Record leads found outside your current slice as ledger rows marked "hand off". Re-read the
code before acting on any row another agent or an earlier pass wrote.
3. Ledger row (every field required)
Group: <id> <the rule in one sentence>
Sites: <file:line (target)> for every copy
Differences:<inputs, outputs, side effects, errors, platform APIs;
"none" only after reading all copies>
Intent: <per difference: commit SHA (`git log -S`, `git log -L`), spec §, or test name;
else "no evidence">
Decision: merge | keep separate | hand off
Home: <existing type/file>; access level; "no new Package.swift edge" verified
Behavior: identical on macOS and Linux (how proven) | changes (see §4)
Tests: <existing test per site that fails if the shared rule breaks>,
or <new test + the mutant it kills>
4. Decide
Keep separate when any of these hold:
- The copies belong to different domain grammars or owners (repo names vs file names).
- The bytes are persisted, hashed or sent on a wire and differ in any way.
- Each seam maps errors to its own type or message, and sharing would erase that.
- The shared form needs a flag or mode parameter that selects behavior.
- The home would add a target dependency or move module-owned code up without a second consumer.
- It is a single platform call with no rule behind it.
- A test copy serves as an independent oracle for production code.
- An "Intent" field holds evidence that the difference is deliberate.
If the merged code would return a different result for any input on macOS or Linux, the
change is a behavior change, not a refactor. Proving it on one platform is not enough.
Either keep the copies separate and list the group under "Kept separate", or ship the change
in its own commit with a test that fails before it. Foundation path and URL APIs differ
between Darwin and swift-corelibs; prove those on Linux (docker run swift:6.4.0-noble) or
keep them separate.
Merge into the owner of the concept: the module that already holds it, ClawCore (with package
access) for a rule used by several targets, ClawTestSupport for test doubles. Callers keep
their own error mapping, defaulted clock or file-manager seams, and domain-typed parameters.
5. Implement and recheck
- Ask the maintainer which branch to use. One commit per merged group.
- After each group: re-read every former site listed in its row, and run its tests.
- Second search: run every seed again plus the new symbol's name. New hits become rows.
- Run
scripts/lint.sh --fix and inspect its diff. Then run scripts/lint.sh, swift build
and swift test.
- Update
docs/ARCHITECTURE.md in the same commit when a contract names the shared rule.
6. PR body
Follow .github/PULL_REQUEST_TEMPLATE.md:
- What changed and why: one short paragraph per merge: the rule, former sites, new home,
why behavior is unchanged.
- Kept separate: one line per important group: what it is and the evidence for keeping it.
- Validation: fill it only after the commands ran. Each line holds a command and the result
it printed, such as
swift test: <N> tests passed. A check you did not run reads
not run: <reason>.
1---2name: removing-duplication3description: Use when asked to find and remove duplicated code or duplicated rules in swift-claw, within one module or across modules and layers (DRY pass, consolidation refactor, "устранить дублирование", shared helper extraction), including duplicated validation, retry, path, config, serialization, error-mapping or resource-handling logic.4metadata:5 source: https://skillmd.com/skills/ivan-magda/removing-duplication6---78# Removing duplication in swift-claw910Duplication means one rule stated twice: the same domain knowledge, not similar-looking lines.11A merge must preserve behavior on every supported platform (macOS and Linux CI). A difference12you cannot prove is accidental stays separate.1314## 1. Before any edit15161. Read `Package.swift` (target edges), `docs/ARCHITECTURE.md` §3.1 (owners), `docs/TESTING.md`.172. Run `swift test` once and record the actual result. The final run is compared to this one.183. Create a ledger file in the scratchpad. Every candidate group gets one row (§3).1920## 2. Two passes2122**Pass 1, per target.** Cover each directory in `Sources/` and `Tests/`. Look for repeated23private helpers, repeated literals that name one thing, and the same guard in several files.2425**Pass 2, across targets, by rule.** Search each category in all of `Sources/`:2627| Rule | Seeds |28| --- | --- |29| Validation | `guard .* else { throw`, `isEmpty`, `".."`, character-set checks |30| Retry, timeouts | `retry`, `backoff`, `sleep(for:`, `deadline`, `duration(to:` |31| Paths | `resolvingSymlinksInPath`, `standardizedFileURL`, `realpath`, `hasPrefix(` |32| Config, env | `environment[`, `CLAW_`, default values parsed from strings |33| Serialization | `JSONEncoder()`, `JSONDecoder()`, `outputFormatting`, `CanonicalJSON` |34| Errors | `catch`, `StoreError`, `classifyError`, user-facing error copy |35| Resources | `FileHandle`, `open(`, `close(`, `defer`, `O_NOFOLLOW` |3637Record leads found outside your current slice as ledger rows marked "hand off". Re-read the38code before acting on any row another agent or an earlier pass wrote.3940## 3. Ledger row (every field required)4142```43Group: <id> <the rule in one sentence>44Sites: <file:line (target)> for every copy45Differences:<inputs, outputs, side effects, errors, platform APIs;46 "none" only after reading all copies>47Intent: <per difference: commit SHA (`git log -S`, `git log -L`), spec §, or test name;48 else "no evidence">49Decision: merge | keep separate | hand off50Home: <existing type/file>; access level; "no new Package.swift edge" verified51Behavior: identical on macOS and Linux (how proven) | changes (see §4)52Tests: <existing test per site that fails if the shared rule breaks>,53 or <new test + the mutant it kills>54```5556## 4. Decide5758Keep separate when any of these hold:59- The copies belong to different domain grammars or owners (repo names vs file names).60- The bytes are persisted, hashed or sent on a wire and differ in any way.61- Each seam maps errors to its own type or message, and sharing would erase that.62- The shared form needs a flag or mode parameter that selects behavior.63- The home would add a target dependency or move module-owned code up without a second consumer.64- It is a single platform call with no rule behind it.65- A test copy serves as an independent oracle for production code.66- An "Intent" field holds evidence that the difference is deliberate.6768If the merged code would return a different result for any input on macOS or Linux, the69change is a behavior change, not a refactor. Proving it on one platform is not enough.70Either keep the copies separate and list the group under "Kept separate", or ship the change71in its own commit with a test that fails before it. Foundation path and URL APIs differ72between Darwin and swift-corelibs; prove those on Linux (`docker run swift:6.4.0-noble`) or73keep them separate.7475Merge into the owner of the concept: the module that already holds it, `ClawCore` (with `package`76access) for a rule used by several targets, `ClawTestSupport` for test doubles. Callers keep77their own error mapping, defaulted clock or file-manager seams, and domain-typed parameters.7879## 5. Implement and recheck80811. Ask the maintainer which branch to use. One commit per merged group.822. After each group: re-read every former site listed in its row, and run its tests.833. Second search: run every seed again plus the new symbol's name. New hits become rows.844. Run `scripts/lint.sh --fix` and inspect its diff. Then run `scripts/lint.sh`, `swift build`85 and `swift test`.865. Update `docs/ARCHITECTURE.md` in the same commit when a contract names the shared rule.8788## 6. PR body8990Follow `.github/PULL_REQUEST_TEMPLATE.md`:9192- **What changed and why:** one short paragraph per merge: the rule, former sites, new home,93 why behavior is unchanged.94- **Kept separate:** one line per important group: what it is and the evidence for keeping it.95- **Validation:** fill it only after the commands ran. Each line holds a command and the result96 it printed, such as `swift test: <N> tests passed`. A check you did not run reads97 `not run: <reason>`.