Skip to content

docs: add .ai-review/instructions.md for repo-specific review context - #357

Open
arshjafri-ripple wants to merge 3 commits into
XRPLF:mainfrom
arshjafri-ripple:main
Open

docs: add .ai-review/instructions.md for repo-specific review context#357
arshjafri-ripple wants to merge 3 commits into
XRPLF:mainfrom
arshjafri-ripple:main

Conversation

@arshjafri-ripple

Copy link
Copy Markdown
Contributor

Summary

Adds a .ai-review/instructions.md file that the AI code reviewer reads before reviewing a pull request. It gives the reviewer context about how this crate actually works, so its comments reflect xrpl-rust's real conventions instead of generic Rust advice. This is a review-guidance file only: it changes no code and no runtime behavior, and it does not affect CI or block merges.

Why

The reviewer is general-purpose. Without repo context it tends to miss the pitfalls specific to a financial SDK and, worse, flag intentional idioms as if they were bugs. This file encodes what a new senior reviewer would need to know before commenting on xrpl-rust, for example:

  • Amount values are strings (XRP amounts are integer drop strings), and the two decimal crates in the tree have a deliberate division of labor.
  • definitions.json has no generator: it is hand-synced from xrpl.js/rippled, so fidelity to upstream is what needs checking, not the hand-edit itself.
  • The crate is no_std-first: library code imports from alloc/core, and theextern crate std as alloc alias is intentional, not a typo.
  • The sync helper modules are hand-maintained wrappers over the async implementation with no automated parity check, so one-sided edits drift silently.
  • Result models are deliberately tolerant of unknown fields from rippled, while the amount structs are deliberately strict; both directions look wrong to a generic reviewer.
  • Signing has XRPL-specific rules (prefix-based key algorithm inference, multisign signer ordering by decoded bytes) where a wrong value fails only on-ledger.

It also tells the reviewer which patterns are deliberate and should not be flagged (the standalone-node genesis credentials in tests, manual ledger advancement, test vectors ported byte-for-byte from xrpl.js).

What's in it

A short, high-signal list grouped by area:

  • Amounts and numbers
  • Binary codec
  • definitions.json
  • Transaction models
  • Cryptography and signing
  • Clients and results
  • Sync/async parity
  • no_std and features
  • Test conventions (idioms not to flag)
  • Contributor conventions

The file is intentionally small so it fits the reviewer's context budget.

How it was built and checked

  • Derived from a scan of the codebase plus a review of what human reviewers have historically commented on in xrpl-rust pull requests.
  • Every rule was validated against the current code on main: each cited file and symbol was opened and confirmed.
  • A separate verification pass then re-checked each rule for accuracy and for false-positive safety (would a reviewer applying it literally flag correct code?), with an independent second review confirming each change. Rules that could cause false positives were narrowed, using counter-examples from this repo's own code and tests.

Notes for reviewers

  • This is guidance, not policy. You can edit it through the normal PR process, and the reviewer will pick up the change.
  • No package behavior changes, so no CHANGELOG entry is included.
  • This follows the same approach as the equivalent file for xrpl.js and xrpl-py, so review guidance stays consistent across the XRPL SDKs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant