feat: improve swapper skill

[gomesalexandre]

Description

Improve with recent gotchas so it's more reliable

⚠️ : this gets improved even more on the PR on top of this!

Issue (if applicable)

closes N/A

Risk

High Risk PRs Require 2 approvals

What protocols, transaction types, wallets or contract interactions might be affected by this PR?

None

Testing

Engineering

• yolo a swapper if you feel like it, or wait for next PR doing so

Operations

• 🏁 My feature is behind a flag and doesn't require operations testing (yet)

None

Screenshots (if applicable)

Summary by CodeRabbit

• Documentation
  • Significantly expanded Swapper Integration guide with architecture framing, activation examples, and phase-based workflow from research to testing and documentation.
  • Added concrete instructions for API discovery, pattern analysis, implementation sequencing, metadata flow, error-handling patterns, status polling, UI integration touchpoints, and feature-flag considerations.
  • Included detailed testing guidance, templates for integration docs, and naming/structural conventions for future swappers.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Rewrites and expands the Swapper Integration Skill doc into an implementation-focused integration guide. Adds metadata/tooling, a Core Architecture section, phase-based workflow (Phases 0–5) with concrete prompts and websearch/fetch steps, detailed swapper patterns, file scaffolds, monadic error patterns, status/metadata flow, testing, and documentation templates.

Changes

Cohort / File(s)

Summary

Swapper Integration Skill Documentation ​.claude/skills/swapper-integration/SKILL.md

Full rewrite: changed tone to production-oriented implementation guide. Added metadata/tooling (WebFetch, WebSearch, Bash(gh pr:*), AskUserQuestion), explicit activation example, Core Architecture (Location, Interfaces, Types, Feature Flags), phase-based workflow (Phases 0–5) with concrete prompts and web steps, detailed swapper pattern taxonomy, directory/file scaffolds and example code patterns (types, constants, helpers, services, fetch wrappers), monadic Result error patterns, metadata/status polling flow, CSP/feature-flag guidance, UI integration touchpoints, expanded testing and INTEGRATION.md template, and naming/structure conventions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Single large documentation file; no code changes.
• Review focus:
  • Consistency between example scaffolds and existing repo conventions (SwapperName enum, metadata keys, file paths).
  • Accuracy of suggested tools/activation phrasing and example prompts.
  • Clarity of phase sequencing and status/metadata propagation patterns.

Suggested reviewers

• NeOMakinG
• 0xApotheosis
• premiumjibles

Poem

🐇 I hopped through docs with eager cheer,

I braided phases, patterns clear,
From fetch to quote and status ping,
A swapper's map I helped to bring,
Code now waits — go build the thing!

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'feat: improve swapper skill' is vague and generic, using non-descriptive terms like 'improve' that don't convey specific details about the substantial changes made to the skill documentation.	Consider a more specific title that highlights the key improvement, such as 'feat: enhance swapper integration skill with architecture guidance and phase-based workflow' to better represent the extensive documentation updates.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat_swapper_skill

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (4)

.claude/skills/swapper-integration/SKILL.md (4)

219-271: Markdown formatting: add language specs and convert emphasis to headings

Three code blocks (lines 227–241, 244–259, 262–271) lack TypeScript language specifiers, and three sections (lines 226, 243, 261) use **Key Pattern:** bold text instead of proper headings. While functional in the skill, this violates markdown-lint rules.

Apply these formatting fixes:

- **Key Pattern: Monadic Error Handling**
+ ### Key Pattern: Monadic Error Handling
- \`\`\`typescript
+ \`\`\`typescript

- **Key Pattern: HTTP Service with Caching**
+ ### Key Pattern: HTTP Service with Caching
- \`\`\`typescript
+ \`\`\`typescript

- **Key Pattern: Rate Calculation**
+ ### Key Pattern: Rate Calculation
- \`\`\`typescript
+ \`\`\`typescript

(Repeat for all three patterns at lines 226, 243, 261.)

Also add language spec to the JSON block at line 1378:

- \`\`\`json
+ \`\`\`json

---

1184-1184: Convert remaining emphasis-as-headings to proper heading markup

Several subsection markers (4e, 4i, 4a, 4b, 4c) use **bold** instead of proper Markdown headings. For consistency with the rest of the document, convert these to #### headings:

Lines 1184, 1258, 1302, 1320, 1334 should change from:

**4e. Feature Flag**

To:

#### 4e. Feature Flag

This aligns with markdown-lint rule MD036 (no-emphasis-as-heading).

Also applies to: 1258-1258, 1302-1302, 1320-1320, 1334-1334

---

1-1504: Overall: Comprehensive rewrite successfully improves guidance with recent gotchas

This substantial expansion of the swapper integration skill substantially delivers on the PR objective to "improve with recent gotchas so it's more reliable."

Strengths:

• New Phase 0 (proactive research) and Phase 2 (pattern analysis) prevent rework before coding starts
• Explicit "Proactive Gotcha Review" section (lines 1283–1296) surfaces 10 critical bugs upfront
• Common Errors section (1462–1486) maps real failures to solutions
• Step-by-step Phase 3 scaffolding with copy-paste code templates covers all 13+ integration layers
• Feature flag, CSP header, metadata handling, and error patterns align with learnings from .cursor/rules/swapper.mdc

Minor issues:

• Referenced documentation files (@reference.md, @common-gotchas.md, @examples.md) are not provided in this PR; verify they exist
• Markdown formatting: 5 sections use **bold** instead of proper headings (MD036); 4 code blocks lack language specs (MD040)
• Placeholder naming convention ([SwapperName], [swapperName], [SWAPPER]) is consistent but could benefit from a brief upfront callout

Verification needed:

• Confirm reference documentation files exist
• Verify file paths in examples (BebopSwapper, NearIntentsSwapper, useTradeButtonProps.tsx, tradeExecution.ts) match current repo structure

---

275-1116: Add explicit placeholder naming guidance at the start of Phase 3

The step-by-step scaffolding (2a–2j) accurately reflects production patterns. Code examples for service factories, error handling, and endpoints align with real implementations (e.g., BebopSwapper uses makeSwapperAxiosServiceMonadic exactly as shown). However, the extensive use of placeholder naming ([SwapperName], [swapperName], [SWAPPER]) throughout Phase 3 lacks upfront explanation.

Suggested improvement: Insert a brief clarification immediately after "Follow this EXACT order to avoid rework:" (line 276):

"Throughout Phase 3, replace [SwapperName] with your swapper's name in PascalCase (e.g., 'BebopSwapper'), [swapperName] in camelCase (e.g., 'bebopService'), and [SWAPPER] in UPPER_CASE (e.g., 'BEBOP_API_KEY')."

This single sentence eliminates potential confusion without altering the technical content.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between d517fe8 and 1c5b2f5.

📒 Files selected for processing (1)

• .claude/skills/swapper-integration/SKILL.md (3 hunks)

🧰 Additional context used

🧠 Learnings (14)

📓 Common learnings

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 11170
File: patches/@shapeshiftoss+bitcoinjs-lib+7.0.0-shapeshift.0.patch:9-19
Timestamp: 2025-11-25T21:43:10.838Z
Learning: In shapeshift/web, gomesalexandre will not expand PR scope to fix latent bugs in unused API surface (like bitcoinjs-lib patch validation methods) when comprehensive testing proves the actual used code paths work correctly, preferring to avoid costly hdwallet/web verdaccio publish cycles and full regression testing for conceptual issues with zero runtime impact.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10569
File: src/plugins/walletConnectToDapps/components/WalletConnectSigningModal/WalletConnectModalSigningFooter.tsx:121-129
Timestamp: 2025-09-17T22:40:30.149Z
Learning: gomesalexandre maintains strict scope discipline even for style/UI PRs in shapeshift/web, declining functionally correct UX improvements (like keeping Cancel button enabled during gas simulation loading) when they fall outside the PR's stated styling objectives, demonstrating his consistent pattern of deferring valid but tangential improvements to separate efforts.

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10323
File: src/components/ButtonWalletPredicate/ButtonWalletPredicate.tsx:7-7
Timestamp: 2025-08-27T09:47:06.275Z
Learning: In shapeshift/web project, NeOMakinG consistently prefers to defer UI/UX improvements and refactoring work (like the Drawer.Close hack fix in ButtonWalletPredicate.tsx) to follow-up PRs rather than expanding the scope of feature PRs, even when the improvements would enhance robustness.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10418
File: src/plugins/walletConnectToDapps/components/header/WalletConnectToDappsHeaderButton.tsx:0-0
Timestamp: 2025-09-08T22:00:48.005Z
Learning: gomesalexandre dismissed an aria-label accessibility suggestion with "meh" in PR #10418 for WalletConnectToDappsHeaderButton.tsx, consistent with the team's pattern of deferring minor a11y improvements to follow-up PRs rather than expanding feature PR scope.

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10231
File: src/components/AssetSearch/components/AssetList.tsx:2-2
Timestamp: 2025-08-08T15:00:49.887Z
Learning: Project shapeshift/web: NeOMakinG prefers avoiding minor a11y/UI nitpicks (e.g., adding aria-hidden to decorative icons in empty states like src/components/AssetSearch/components/AssetList.tsx) within feature PRs; defer such suggestions to a follow-up instead of blocking the PR.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/EIP712MessageDisplay.tsx:21-24
Timestamp: 2025-09-12T13:16:27.004Z
Learning: gomesalexandre declined to add error boundaries to WalletConnect modals in PR #10461, stating "no error boundaries in this pr ser", consistent with his preference to keep PR scope focused and defer tangential improvements to separate efforts.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10206
File: src/config.ts:127-128
Timestamp: 2025-08-07T11:20:44.614Z
Learning: gomesalexandre prefers required environment variables without default values in the config file (src/config.ts). They want explicit configuration and fail-fast behavior when environment variables are missing, rather than having fallback defaults.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/ContractInteractionBreakdown.tsx:0-0
Timestamp: 2025-09-13T16:45:18.813Z
Learning: gomesalexandre prefers aggressively deleting unused/obsolete code files ("ramboing") rather than fixing technical issues in code that won't be used, demonstrating his preference for keeping codebases clean and PR scope focused.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10458
File: src/plugins/walletConnectToDapps/types.ts:7-7
Timestamp: 2025-09-10T15:34:29.604Z
Learning: gomesalexandre is comfortable relying on transitive dependencies (like abitype through ethers/viem) rather than explicitly declaring them in package.json, preferring to avoid package.json bloat when the transitive dependency approach works reliably in practice.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10503
File: .env:56-56
Timestamp: 2025-09-16T13:17:02.938Z
Learning: gomesalexandre prefers to enable feature flags globally in the base .env file when the intent is to activate features everywhere, even when there are known issues like crashes, demonstrating his preference for intentional global feature rollouts over cautious per-environment enablement.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10249
File: src/pages/ThorChainLP/components/ReusableLpStatus/TransactionRow.tsx:447-503
Timestamp: 2025-08-13T17:07:10.763Z
Learning: gomesalexandre prefers relying on TypeScript's type system for validation rather than adding defensive runtime null checks when types are properly defined. They favor a TypeScript-first approach over defensive programming with runtime validations.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10276
File: src/hooks/useActionCenterSubscribers/useThorchainLpDepositActionSubscriber.tsx:61-66
Timestamp: 2025-08-14T17:51:47.556Z
Learning: gomesalexandre is not concerned about structured logging and prefers to keep console.error usage as-is rather than implementing structured logging patterns, even when project guidelines suggest otherwise.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10413
File: src/components/Modals/FiatRamps/fiatRampProviders/onramper/utils.ts:29-55
Timestamp: 2025-09-02T14:26:19.028Z
Learning: gomesalexandre prefers to keep preparatory/reference code simple until it's actively consumed, rather than implementing comprehensive error handling, validation, and robustness improvements upfront. They prefer to add these improvements when the code is actually being used in production.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10276
File: src/pages/ThorChainLP/components/ReusableLpStatus/TransactionRow.tsx:396-402
Timestamp: 2025-08-14T17:55:57.490Z
Learning: gomesalexandre is comfortable with functions/variables that return undefined or true (tri-state) when only the truthy case matters, preferring to rely on JavaScript's truthy/falsy behavior rather than explicitly returning boolean values.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10783
File: src/context/ModalStackProvider/useModalRegistration.ts:30-41
Timestamp: 2025-10-16T11:14:40.657Z
Learning: gomesalexandre prefers to add lint rules (like typescript-eslint/strict-boolean-expressions for truthiness checks on numbers) to catch common issues project-wide rather than relying on code review to catch them.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10206
File: src/lib/moralis.ts:47-85
Timestamp: 2025-08-07T11:22:16.983Z
Learning: gomesalexandre prefers console.error over structured logging for Moralis API integration debugging, as they find it more conventional and prefer to examine XHR requests directly rather than rely on structured logs for troubleshooting.

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/**/*.ts : Use TypeScript with explicit types (e.g., SupportedChainIds) for all code in the Swapper system

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/**/*.test.ts : Write unit tests for swapper methods and API endpoints

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/**/*.ts : Avoid side effects in swap logic; ensure swap methods are deterministic and stateless

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/**/*.ts : Use PascalCase for types, interfaces, and enums in the Swapper system

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/**/*.ts : Adhere to the Swapper directory structure: each swapper resides in packages/swapper/src/swappers/<SwapperName>/ with required files (SwapperName.ts, endpoints.ts, types.ts, utils/constants.ts, utils/helpers.ts)

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : All swappers must implement the Swapper interface from packages/swapper/src/types.ts

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/endpoints.ts : All swapper API implementations must implement the SwapperApi interface from packages/swapper/src/types.ts

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:17.804Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/error-handling.mdc:0-0
Timestamp: 2025-11-24T21:20:17.804Z
Learning: Applies to **/swapper{s,}/**/*.{ts,tsx} : ALWAYS use `makeSwapErrorRight` for swapper errors with `TradeQuoteError` enum for error codes and provide detailed error information

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : Reuse executeEvmTransaction utility for EVM-based swappers instead of implementing custom transaction execution

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/**/*.ts : Swapper files must be located in packages/swapper/src/swappers/ directory structure and not placed outside this location

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/**/*.ts : Validate inputs and log errors for debugging in Swapper system implementations

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/utils/constants.ts : Define supported chain IDs for each swapper in utils/constants.ts with both 'sell' and 'buy' properties following the pattern: SupportedChainIds type

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : Implement filterBuyAssetsBySellAssetId method to filter assets by supported chain IDs in the buy property

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

🪛 LanguageTool

.claude/skills/swapper-integration/SKILL.md

[style] ~1336-~1336: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...delta < 0.1% 4c. Edge Cases - [ ] Very small amounts (near minimum) - [ ] Very large...

(EN_WEAK_ADJECTIVE)

---

[style] ~1337-~1337: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...Very small amounts (near minimum) - [ ] Very large amounts (near maximum) - [ ] High slipp...

(EN_WEAK_ADJECTIVE)

🪛 markdownlint-cli2 (0.18.1)

.claude/skills/swapper-integration/SKILL.md

41-41: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

60-60: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

66-66: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

226-226: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

243-243: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

261-261: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1184-1184: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1258-1258: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1302-1302: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1320-1320: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1334-1334: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1407-1407: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Call / Static

🔇 Additional comments (5)

.claude/skills/swapper-integration/SKILL.md (5)

1-33: Strong metadata and architectural framing

The updated description, expanded tool allowlist, and new Architecture section provide clear activation context and establish the skill's scope effectively. The "Your Role" statement (line 30) anchors expectations well.

---

36-72: Phase 0 research guidance is pragmatic

The proactive search pattern (docs → website → GitHub examples → chain support) before asking the user reduces back-and-forth and accelerates the workflow. Clear, actionable steps.

---

75-133: Phase 1 information gathering is thorough

Critical API behaviors (slippage format, address checksumming, native token handling) are proactively surfaced. The multi-question AskUserQuestion example (lines 107-133) is ready to adapt and provides clear structure for multi-select scenarios.

---

1300-1407: Phase 4 and 5 provide strong testing and documentation guidance

The automated checks (type-check, lint, build) gate quality before manual testing. The 13-item manual checklist covers critical paths: quotes, rates, approvals, native/wrapped tokens, error handling, and cross-account trades. Edge cases section (lines 1334–1342) includes gas spikes and API timeouts—realistic scenarios. The INTEGRATION.md template (lines 1347–1407) with API details, slippage/address/native-token notes, and gotchas section ensures future integrators have clear reference docs.

---

1008-1116: Correct line number for metadata extraction in tradeExecution.ts to ~176 instead of 156–161

Step 3 appropriately skips metadata implementation for simple EVM swappers but provides comprehensive guidance for deposit-to-address swappers. The instruction to add metadata in TWO required places (useTradeButtonProps + tradeExecution.ts) is critical and well-emphasized. File paths are accurate; however, the metadata extraction point in tradeExecution.ts occurs around line 176, not lines 156–161 as stated.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

.claude/skills/swapper-integration/SKILL.md (2)

1412-1412: Add language specifier to JSON code block

Line 1412's code block should include a language identifier for proper syntax highlighting and parsing.

- ```json
+ ```json

---

1341-1342: Replace weak intensifiers in checklist items

Lines 1341–1342 use "Very small" and "Very large," which are over-used intensifiers. Consider replacing with more specific or alternative phrasing to improve clarity:

• "Very small amounts (near minimum)" → "Minimal amounts (near minimum)" or "Edge case: dust amounts"
• "Very large amounts (near maximum)" → "Maximal amounts (near maximum)" or "Edge case: max capacity"

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 1c5b2f5 and 2f6f7ec.

📒 Files selected for processing (1)

• .claude/skills/swapper-integration/SKILL.md (3 hunks)

🧰 Additional context used

🧠 Learnings (30)

📓 Common learnings

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10569
File: src/plugins/walletConnectToDapps/components/WalletConnectSigningModal/WalletConnectModalSigningFooter.tsx:121-129
Timestamp: 2025-09-17T22:40:30.149Z
Learning: gomesalexandre maintains strict scope discipline even for style/UI PRs in shapeshift/web, declining functionally correct UX improvements (like keeping Cancel button enabled during gas simulation loading) when they fall outside the PR's stated styling objectives, demonstrating his consistent pattern of deferring valid but tangential improvements to separate efforts.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 11170
File: patches/@shapeshiftoss+bitcoinjs-lib+7.0.0-shapeshift.0.patch:9-19
Timestamp: 2025-11-25T21:43:10.838Z
Learning: In shapeshift/web, gomesalexandre will not expand PR scope to fix latent bugs in unused API surface (like bitcoinjs-lib patch validation methods) when comprehensive testing proves the actual used code paths work correctly, preferring to avoid costly hdwallet/web verdaccio publish cycles and full regression testing for conceptual issues with zero runtime impact.

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10323
File: src/components/ButtonWalletPredicate/ButtonWalletPredicate.tsx:7-7
Timestamp: 2025-08-27T09:47:06.275Z
Learning: In shapeshift/web project, NeOMakinG consistently prefers to defer UI/UX improvements and refactoring work (like the Drawer.Close hack fix in ButtonWalletPredicate.tsx) to follow-up PRs rather than expanding the scope of feature PRs, even when the improvements would enhance robustness.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/EIP712MessageDisplay.tsx:21-24
Timestamp: 2025-09-12T13:16:27.004Z
Learning: gomesalexandre declined to add error boundaries to WalletConnect modals in PR #10461, stating "no error boundaries in this pr ser", consistent with his preference to keep PR scope focused and defer tangential improvements to separate efforts.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10418
File: src/plugins/walletConnectToDapps/components/header/WalletConnectToDappsHeaderButton.tsx:0-0
Timestamp: 2025-09-08T22:00:48.005Z
Learning: gomesalexandre dismissed an aria-label accessibility suggestion with "meh" in PR #10418 for WalletConnectToDappsHeaderButton.tsx, consistent with the team's pattern of deferring minor a11y improvements to follow-up PRs rather than expanding feature PR scope.

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10231
File: src/components/AssetSearch/components/AssetList.tsx:2-2
Timestamp: 2025-08-08T15:00:49.887Z
Learning: Project shapeshift/web: NeOMakinG prefers avoiding minor a11y/UI nitpicks (e.g., adding aria-hidden to decorative icons in empty states like src/components/AssetSearch/components/AssetList.tsx) within feature PRs; defer such suggestions to a follow-up instead of blocking the PR.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 11016
File: packages/swapper/src/swappers/NearIntentsSwapper/swapperApi/getTradeQuote.ts:93-93
Timestamp: 2025-11-12T12:48:02.977Z
Learning: In the swapper architecture, timeout handling is implemented at the abstraction layer in packages/swapper/src/swapper.ts using timeoutMonadic, which wraps all calls to individual swapper implementations. Individual swapper implementations (e.g., NearIntentsSwapper, PortalsSwapper, etc.) should NOT use timeoutMonadic directly—they simply return their results and the abstraction layer handles timeout concerns centrally.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10206
File: src/config.ts:127-128
Timestamp: 2025-08-07T11:20:44.614Z
Learning: gomesalexandre prefers required environment variables without default values in the config file (src/config.ts). They want explicit configuration and fail-fast behavior when environment variables are missing, rather than having fallback defaults.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/ContractInteractionBreakdown.tsx:0-0
Timestamp: 2025-09-13T16:45:18.813Z
Learning: gomesalexandre prefers aggressively deleting unused/obsolete code files ("ramboing") rather than fixing technical issues in code that won't be used, demonstrating his preference for keeping codebases clean and PR scope focused.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10458
File: src/plugins/walletConnectToDapps/types.ts:7-7
Timestamp: 2025-09-10T15:34:29.604Z
Learning: gomesalexandre is comfortable relying on transitive dependencies (like abitype through ethers/viem) rather than explicitly declaring them in package.json, preferring to avoid package.json bloat when the transitive dependency approach works reliably in practice.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10503
File: .env:56-56
Timestamp: 2025-09-16T13:17:02.938Z
Learning: gomesalexandre prefers to enable feature flags globally in the base .env file when the intent is to activate features everywhere, even when there are known issues like crashes, demonstrating his preference for intentional global feature rollouts over cautious per-environment enablement.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10249
File: src/pages/ThorChainLP/components/ReusableLpStatus/TransactionRow.tsx:447-503
Timestamp: 2025-08-13T17:07:10.763Z
Learning: gomesalexandre prefers relying on TypeScript's type system for validation rather than adding defensive runtime null checks when types are properly defined. They favor a TypeScript-first approach over defensive programming with runtime validations.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10276
File: src/hooks/useActionCenterSubscribers/useThorchainLpDepositActionSubscriber.tsx:61-66
Timestamp: 2025-08-14T17:51:47.556Z
Learning: gomesalexandre is not concerned about structured logging and prefers to keep console.error usage as-is rather than implementing structured logging patterns, even when project guidelines suggest otherwise.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10413
File: src/components/Modals/FiatRamps/fiatRampProviders/onramper/utils.ts:29-55
Timestamp: 2025-09-02T14:26:19.028Z
Learning: gomesalexandre prefers to keep preparatory/reference code simple until it's actively consumed, rather than implementing comprehensive error handling, validation, and robustness improvements upfront. They prefer to add these improvements when the code is actually being used in production.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10276
File: src/pages/ThorChainLP/components/ReusableLpStatus/TransactionRow.tsx:396-402
Timestamp: 2025-08-14T17:55:57.490Z
Learning: gomesalexandre is comfortable with functions/variables that return undefined or true (tri-state) when only the truthy case matters, preferring to rely on JavaScript's truthy/falsy behavior rather than explicitly returning boolean values.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10783
File: src/context/ModalStackProvider/useModalRegistration.ts:30-41
Timestamp: 2025-10-16T11:14:40.657Z
Learning: gomesalexandre prefers to add lint rules (like typescript-eslint/strict-boolean-expressions for truthiness checks on numbers) to catch common issues project-wide rather than relying on code review to catch them.

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10206
File: src/lib/moralis.ts:47-85
Timestamp: 2025-08-07T11:22:16.983Z
Learning: gomesalexandre prefers console.error over structured logging for Moralis API integration debugging, as they find it more conventional and prefer to examine XHR requests directly rather than rely on structured logs for troubleshooting.

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/**/*.ts : Use TypeScript with explicit types (e.g., SupportedChainIds) for all code in the Swapper system

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/**/*.ts : Use PascalCase for types, interfaces, and enums in the Swapper system

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:17.804Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/error-handling.mdc:0-0
Timestamp: 2025-11-24T21:20:17.804Z
Learning: Applies to **/swapper{s,}/**/*.{ts,tsx} : ALWAYS use `makeSwapErrorRight` for swapper errors with `TradeQuoteError` enum for error codes and provide detailed error information

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/**/*.ts : Adhere to the Swapper directory structure: each swapper resides in packages/swapper/src/swappers/<SwapperName>/ with required files (SwapperName.ts, endpoints.ts, types.ts, utils/constants.ts, utils/helpers.ts)

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : All swappers must implement the Swapper interface from packages/swapper/src/types.ts

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/**/*.ts : Use camelCase for variable and function names in the Swapper system

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/endpoints.ts : Reuse checkEvmSwapStatus utility for checking EVM swap status instead of implementing custom status checks

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/**/*.ts : Avoid side effects in swap logic; ensure swap methods are deterministic and stateless

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/**/*.ts : Swapper files must be located in packages/swapper/src/swappers/ directory structure and not placed outside this location

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/**/*.ts : Validate inputs and log errors for debugging in Swapper system implementations

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/**/*.test.ts : Write unit tests for swapper methods and API endpoints

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-08-08T15:00:22.321Z

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10231
File: src/components/MultiHopTrade/components/TradeInput/components/HighlightedTokens.tsx:14-14
Timestamp: 2025-08-08T15:00:22.321Z
Learning: In shapeshift/web reviews for NeOMakinG, avoid nitpicks to change deep-relative imports to '@/…' alias paths within feature/non-refactor PRs; defer such style-only changes to a dedicated follow-up refactor unless they fix an issue.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-08-22T13:02:38.078Z

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10323
File: src/pages/Explore/Explore.tsx:91-92
Timestamp: 2025-08-22T13:02:38.078Z
Learning: In the ShapeShift web codebase, feature flags are consistently used as string literals with the useFeatureFlag hook (e.g., useFeatureFlag('RfoxFoxEcosystemPage')), not as enums. The hook accepts keyof FeatureFlags which provides type safety through the TypeScript type system rather than requiring an enum. This is the established pattern used throughout the entire codebase.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:04.979Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T21:20:04.979Z
Learning: To add a new feature flag: (1) Add to `FeatureFlags` type in `src/state/slices/preferencesSlice/preferencesSlice.ts`, (2) Add environment variable validation in `src/config.ts`, (3) Add to initial state in `preferencesSlice.ts`, (4) Add to test mock in `src/test/mocks/store.ts`, (5) Set appropriate values in `.env`, `.env.development`, and `.env.production`

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-09-17T22:40:30.149Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10569
File: src/plugins/walletConnectToDapps/components/WalletConnectSigningModal/WalletConnectModalSigningFooter.tsx:121-129
Timestamp: 2025-09-17T22:40:30.149Z
Learning: gomesalexandre maintains strict scope discipline even for style/UI PRs in shapeshift/web, declining functionally correct UX improvements (like keeping Cancel button enabled during gas simulation loading) when they fall outside the PR's stated styling objectives, demonstrating his consistent pattern of deferring valid but tangential improvements to separate efforts.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-09-12T13:16:27.004Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/EIP712MessageDisplay.tsx:21-24
Timestamp: 2025-09-12T13:16:27.004Z
Learning: gomesalexandre declined to add error boundaries to WalletConnect modals in PR #10461, stating "no error boundaries in this pr ser", consistent with his preference to keep PR scope focused and defer tangential improvements to separate efforts.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-09-10T15:35:46.223Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10458
File: src/plugins/walletConnectToDapps/components/modals/EIP155SignTypedDataConfirmation.tsx:55-55
Timestamp: 2025-09-10T15:35:46.223Z
Learning: gomesalexandre prefers fail-fast early returns over graceful degradation when critical data is missing in WalletConnect flows (like peer metadata in EIP155SignTypedDataConfirmation.tsx). He favors "safety first, always double-wrap" approach and believes missing peer metadata indicates bigger problems that should be surfaced explicitly rather than masked with partial UI rendering.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-08-27T09:47:06.275Z

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10323
File: src/components/ButtonWalletPredicate/ButtonWalletPredicate.tsx:7-7
Timestamp: 2025-08-27T09:47:06.275Z
Learning: In shapeshift/web project, NeOMakinG consistently prefers to defer UI/UX improvements and refactoring work (like the Drawer.Close hack fix in ButtonWalletPredicate.tsx) to follow-up PRs rather than expanding the scope of feature PRs, even when the improvements would enhance robustness.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-25T21:43:10.838Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 11170
File: patches/@shapeshiftoss+bitcoinjs-lib+7.0.0-shapeshift.0.patch:9-19
Timestamp: 2025-11-25T21:43:10.838Z
Learning: In shapeshift/web, gomesalexandre will not expand PR scope to fix latent bugs in unused API surface (like bitcoinjs-lib patch validation methods) when comprehensive testing proves the actual used code paths work correctly, preferring to avoid costly hdwallet/web verdaccio publish cycles and full regression testing for conceptual issues with zero runtime impact.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-09-12T12:00:33.924Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/modals/SendTransactionConfirmation.tsx:42-50
Timestamp: 2025-09-12T12:00:33.924Z
Learning: gomesalexandre prefers maintaining consistency with existing code patterns in WalletConnect modals, including side-effects-during-render for error handling (showErrorToast + handleReject), rather than introducing isolated refactors that would make the codebase inconsistent.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-09-12T10:35:51.632Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/utils/tenderly/index.ts:33-45
Timestamp: 2025-09-12T10:35:51.632Z
Learning: gomesalexandre consistently dismisses CodeRabbit suggestions about replacing console.error/console.warn with structured logging in API integration code, preferring simple console logging for debugging Tenderly transaction simulation APIs in WalletConnect flows.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-08-08T15:00:49.887Z

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10231
File: src/components/AssetSearch/components/AssetList.tsx:2-2
Timestamp: 2025-08-08T15:00:49.887Z
Learning: Project shapeshift/web: NeOMakinG prefers avoiding minor a11y/UI nitpicks (e.g., adding aria-hidden to decorative icons in empty states like src/components/AssetSearch/components/AssetList.tsx) within feature PRs; defer such suggestions to a follow-up instead of blocking the PR.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-09-12T12:04:24.562Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10461
File: src/plugins/walletConnectToDapps/components/WalletConnectSigningModal/content/TransactionContent.tsx:40-140
Timestamp: 2025-09-12T12:04:24.562Z
Learning: gomesalexandre prefers to defer error handling improvements in new/preparatory code until real-world error cases are encountered, rather than implementing speculative error handling without concrete failure scenarios to test against. This aligns with keeping PR scope focused and evidence-based development practices.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-09-08T22:00:48.005Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10418
File: src/plugins/walletConnectToDapps/components/header/WalletConnectToDappsHeaderButton.tsx:0-0
Timestamp: 2025-09-08T22:00:48.005Z
Learning: gomesalexandre dismissed an aria-label accessibility suggestion with "meh" in PR #10418 for WalletConnectToDappsHeaderButton.tsx, consistent with the team's pattern of deferring minor a11y improvements to follow-up PRs rather than expanding feature PR scope.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/endpoints.ts : All swapper API implementations must implement the SwapperApi interface from packages/swapper/src/types.ts

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : Reuse executeEvmTransaction utility for EVM-based swappers instead of implementing custom transaction execution

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/utils/constants.ts : Define supported chain IDs for each swapper in utils/constants.ts with both 'sell' and 'buy' properties following the pattern: SupportedChainIds type

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-24T21:20:57.909Z

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : Implement filterBuyAssetsBySellAssetId method to filter assets by supported chain IDs in the buy property

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

📚 Learning: 2025-11-03T22:31:30.786Z

Learnt from: gomesalexandre
Repo: shapeshift/web PR: 10985
File: packages/swapper/src/swappers/PortalsSwapper/getPortalsTradeQuote/getPortalsTradeQuote.ts:0-0
Timestamp: 2025-11-03T22:31:30.786Z
Learning: In packages/swapper/src/swappers/PortalsSwapper, the rate and quote files intentionally use different approaches for calculating buyAmountBeforeSlippageCryptoBaseUnit: getPortalsTradeRate.tsx uses minOutputAmount / (1 - buffer) for conservative estimates, while getPortalsTradeQuote.ts uses outputAmount / (1 - buffer) for final quote display. This difference is validated by on-chain simulation testing and is intentional.

Applied to files:

• .claude/skills/swapper-integration/SKILL.md

🪛 LanguageTool

.claude/skills/swapper-integration/SKILL.md

[style] ~1341-~1341: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...delta < 0.1% 4c. Edge Cases - [ ] Very small amounts (near minimum) - [ ] Very large...

(EN_WEAK_ADJECTIVE)

---

[style] ~1342-~1342: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...Very small amounts (near minimum) - [ ] Very large amounts (near maximum) - [ ] High slipp...

(EN_WEAK_ADJECTIVE)

🪛 markdownlint-cli2 (0.18.1)

.claude/skills/swapper-integration/SKILL.md

1307-1307: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1325-1325: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1339-1339: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

1412-1412: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (1)

.claude/skills/swapper-integration/SKILL.md (1)

1-1505: Comprehensive swapper integration skill guide — well structured and aligned with codebase patterns

This rewrite successfully transforms the skill from a process overview into an actionable, implementation-focused guide with concrete code scaffolding. The Phase 0–5 workflow progression (research → information gathering → pattern analysis → implementation → testing → documentation) is clear and practical.

Strengths:

• Proactive research phase: Phase 0's WebFetch/WebSearch guidance with concrete search queries is a strong addition that shifts left (researches before asking user).
• Pattern analysis: Swapper category taxonomy (EVM Direct, Deposit-to-Address, Gasless, Solana-only, etc.) provides clear decision guidance.
• Code scaffolding: Extensive pseudo-code examples (types.ts, helpers.ts, service.ts, quote/rate logic, endpoints.ts, registration) are properly placeholder-named and demonstrate monadic error handling, caching, and metadata patterns consistent with learnings.
• Metadata handling: Step 3 (lines 1006–1113) clearly explains swapper-specific metadata for deposit-to-address patterns and references exact UI integration points.
• Feature flag wiring: Lines 1186–1230 correctly show direct flag destructuring (e.g., BebopSwap) matching current codebase pattern from learnings, not enum-based switching.
• Gotchas section: The 10 critical gotchas (lines 1288–1303) are concrete and prevent common pitfalls (slippage format, checksumming, hex conversion, affiliate fees).
• Completion checklist: Lines 1426–1465 provide a clear exit criteria covering code quality, functionality, integration, documentation, and testing.

Alignment with learnings:

• Monadic error handling (lines 222–237) matches error-handling.mdc rules.
• Feature flag pattern (lines 1186–1230) matches actual codebase (destructure flags, not enum switches).
• Swapper structure and interfaces correctly reference existing patterns.

[0xApotheosis]

Gold