--- name: bsv-design-review description: "Review a BSV wallet, app, screen, flow or diff against the bitcoinsv.design guide, and report findings that each cite the rule they come from, most costly first. Use when asked to 'review this screen', 'check this against the BSV design guide', 'is this flow right for BSV', 'design review', 'audit our wallet', or before shipping any BSV interface." --- > Start from [bitcoinsv-design](../bitcoinsv-design/SKILL.md). Shared states, labels, errors, amounts and fees: [shared patterns](../bitcoinsv-design/references/shared-patterns.md). # Review a BSV product against the guide **Scope:** Checking a piece of work against the rules that apply to it, and writing findings somebody can check. **Does NOT cover:** - Designing a flow from scratch; load the skill for that flow - Code review for correctness or security **Cross-references:** [bsv-payments](../bsv-payments/SKILL.md), [bsv-wallet-connection](../bsv-wallet-connection/SKILL.md), [bsv-backup-and-recovery](../bsv-backup-and-recovery/SKILL.md), [shared patterns](../bitcoinsv-design/references/shared-patterns.md). The guide states several hundred do-and-don't rules, each tagged critical (it can cost somebody money or access to it), high (it costs trust or privacy) or standard. This skill is the procedure for checking a piece of work against the ones that apply, and reporting what it finds so that the costly findings are read first. The ALWAYS / NEVER lists below are the most costly rules in the whole guide. ## ALWAYS - Make the irreversible step unmistakable. A payment cannot be recalled, so the review screen is the last line of defence. _([costs money](https://www.bitcoinsv.design/guide/rule/b502171c81/))_ - Show the total a payment takes from the user, who it goes to, and that it cannot be undone, before they commit. _([costs money](https://www.bitcoinsv.design/guide/rule/72c3ab54e4/))_ - Name the limits. "This backup covers your keys but not your payment records" is the sentence that stops somebody losing money later. _([costs money](https://www.bitcoinsv.design/guide/rule/02cda8cac2/))_ - Show the profile name and avatar the handle resolved to, before the confirm button. Paying "Anna Keller" is checkable; paying anna@examplebank.com is only spellable. _([costs money](https://www.bitcoinsv.design/guide/rule/344afceabd/))_ - Say when the key behind a saved contact has changed since last time, and make the user acknowledge it. A silently rotated key is how a handle gets hijacked. _([costs money](https://www.bitcoinsv.design/guide/rule/f47f34353f/))_ - Make the handle the default and the address the fallback. Every payment that uses a handle is a payment that cannot go to the wrong network. _([costs money](https://www.bitcoinsv.design/guide/rule/98fc09f14d/))_ ## NEVER - Build a product where the user's funds depend on your company continuing to exist. Every wallet should be recoverable without you. See Backups. _([costs money](https://www.bitcoinsv.design/guide/rule/665b6af4ce/))_ - Let recovery words reach a screenshot, a cloud note, a password manager on the same device, or a chat message. _([costs money](https://www.bitcoinsv.design/guide/rule/762c70a9c3/))_ - Let the everyday wallet draw from savings on its own, or let an agent raise its own budget. Both turn a bridge into a leak. _([costs money](https://www.bitcoinsv.design/guide/rule/8d5c89ed47/))_ - Show an amount taken from the app's description text. Show the amount from the request itself, and warn if the two disagree. _([costs money](https://www.bitcoinsv.design/guide/rule/b50f273390/))_ - Let an AI agent approve key linkage, share a Pass, or widen its own permissions. _([costs money](https://www.bitcoinsv.design/guide/rule/be5632560c/))_ - Show long decimal BSV amounts in a consumer interface. "0.00012500 BSV" asks the reader to count zeros, and they will get it wrong. _([costs money](https://www.bitcoinsv.design/guide/rule/5fe9c5b068/))_ ## Patterns _Design guidance in each pattern comes from the guide page it cites. Method names, arguments and code are implementation notes checked against `@bsv/sdk` 4.0.0._ ### 1. Pick the scope, then review **When:** Any review. Choosing the wrong rule set wastes most of the effort. **How:** 1. Get the work itself in front of you: a screenshot, a Figma frame, a diff, a running build. Do not review from a description; most rules are about a specific screen. 2. Choose the reference: `references/spending-wallet.md` for a wallet people pay with, `references/connected-app.md` for an app that asks a wallet to act, `references/savings.md` for savings, shared or inherited money. Read each one that applies if the work spans more than one. 3. Each reference opens with its critical and high rules. Check every one of those that the work touches before reading further. 4. Then skim the rest by page for the rules the work touches. A rule that does not apply is not a finding. **Fallback:** If the work fits no profile, fetch `/api/rules.json` and filter by the guide pages that cover what you are looking at. _Source: [Common user flows](https://www.bitcoinsv.design/guide/designing-products/common-user-flows/)_ ### 2. Write findings somebody can check **When:** Every finding, without exception. **How:** 1. State what you saw, which rule it breaks, and the rule's own URL (`/guide/rule//`). A finding without the URL is an opinion. 2. Quote the rule; do not paraphrase it. The reader has to be able to open the sentence and disagree. 3. Order by severity: critical, then high, then standard. An irreversible payment to the wrong place outranks a label that could be clearer. 4. Label anything the guide does not state as your own opinion, or leave it out. 5. End by saying what you could not check. A review of three screens out of nine is a review of three screens. _Source: [Checklists](https://www.bitcoinsv.design/checklist/)_ ### 3. Look rules up live instead of loading them **When:** Mid-task, when one question needs one rule rather than a whole reference. **How:** 1. The MCP server at `/mcp/` answers `list_rules` with a profile or a page path, and `search_guide` with a phrase. 2. `/api/rules.json` is the full list, most costly first, with each rule's page and citation URL. _Source: [Skills](https://www.bitcoinsv.design/skills/)_ ## All the rules `references/spending-wallet.md`: An everyday spending wallet, 369 rules, most costly first. `references/connected-app.md`: An app that connects to a wallet, 349 rules, most costly first. `references/savings.md`: Savings, shared or inherited money, 306 rules, most costly first. Every rule in the guide, most costly first: https://www.bitcoinsv.design/api/rules.json ## Implementation resources - **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk. - **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app. - **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number. --- _Generated from https://www.bitcoinsv.design/, Open BSV License Version 6. Rules are extracted from the guide's pages and cannot be out of date about what it says; the patterns may still need updating._