refactor: added to natspecs design decision

Author: skimaharvey

src/core/MultistrategyVault.sol

@@ -39,6 +39,18 @@ import { DebtManagementLib } from "src/core/libs/DebtManagementLib.sol";
  *   and it is the responsibility of those that hold the corresponding roles to choose
  *   and fund strategies that best fit their desired specifications.
  *
+ * @custom:design-decisions
+ * 1. Function Naming: External functions use snake_case (e.g., set_deposit_limit, process_report)
+ *    to maintain exact compatibility with the Vyper implementation, ensuring existing integrations
+ *    continue to work seamlessly.
+ *
+ * 2. Withdraw/Redeem Overloads: Due to Solidity contract size constraints, we implement only the
+ *    most essential function overloads:
+ *    - 3-parameter versions for ERC4626 compliance
+ *    - 5-parameter versions for advanced usage with maxLoss and custom strategies
+ *    The Vyper version includes additional 4-parameter overloads which were intentionally omitted
+ *    to keep the contract size manageable while maintaining full functionality.
+ *
  *   Those holding vault tokens are able to redeem the tokens for the corresponding
  *   amount of underlying asset based on any reported profits or losses since their
  *   initial deposit.

src/core/interfaces/IMultistrategyVault.sol

@@ -8,6 +8,17 @@ pragma solidity ^0.8.25;
  * @custom:ported-from https://github.com/yearn/yearn-vaults-v3/blob/master/contracts/interfaces/IVault.sol
  * @notice Interface for MultistrategyVault ERC4626-compliant vault with multiple strategies
  * @dev Defines all external functions, events, errors, and types for the vault
+ *
+ * @custom:design-decisions
+ * 1. Function Naming Convention: All external functions use snake_case to maintain 1:1 compatibility
+ *    with the original Vyper implementation. This ensures seamless integration for existing consumers.
+ *
+ * 2. Withdraw/Redeem Functions: The interface includes multiple overloads for withdraw/redeem operations:
+ *    - 3-parameter versions: Basic ERC4626 compliant functions with default parameters
+ *    - 5-parameter versions: Advanced functions with maxLoss and custom strategies parameters
+ *    Note: Additional overloads with loss parameters exist in Vyper but were omitted due to Solidity
+ *    contract size constraints. The 3 and 5 parameter versions provide equivalent functionality
+ *    while maintaining ERC4626 compliance.
  */
 interface IMultistrategyVault {
     // ============================================