weasel-overview

name	weasel-overview
description	Project overview and audit preparation for smart contract security. Triggers on weasel overview, weasel scope, or weasel onboard.

Weasel Overview

Project overview and audit scoping for security engineers starting a new audit.

When to Activate

• Starting a new audit
• User asks "what does this project do?"
• User wants to scope/understand a codebase

When NOT to Use

• User wants to run static analysis (→ weasel-analyzer)
• User wants to explain specific code (→ weasel-explainer)
• User already understands the project and wants to audit

Process

1. Read Documentation

• README.md - project description, architecture
• docs/ folder if exists
• Comments in main contracts
• Previous audits - Check for audit/, audits/, or audit reports
• Known issues - Check known-issues.md, issue tracker links

2. Map Project Structure

• List all .sol files
• Identify: core contracts vs libraries vs interfaces
• Map inheritance hierarchy
• Note external dependencies (OpenZeppelin, Chainlink, etc.)

3. Identify Entry Points

User Functions (highest risk - untrusted input):

• deposit(), withdraw(), swap(), transfer()...
• Any external/public that handles value

Admin Functions (check access control):

• setFee(), pause(), upgrade()...
• Note: what permissions? onlyOwner? Multisig?

Callbacks (reentrancy risk):

• onFlashLoan(), uniswapV3Callback()...
• Any function called by external contracts

4. Trace Value Flow

• Inbound: How does ETH/tokens enter? (deposit, swap, mint)
• Outbound: How does ETH/tokens exit? (withdraw, claim, burn)
• Internal: How does value move between contracts?

5. Map Trust Boundaries

Untrusted - assume malicious:

• Users, external contracts, oracles

Privileged - trusted but verify:

• Owner/Admin, Governance, Keepers

Internal - trusted:

• Protocol's own contracts, libraries

6. Identify Focus Areas

Project Type	High-Risk Areas
DeFi/Lending	Liquidation, interest calc, oracles, flash loans
DEX/AMM	Price calc, slippage, LP math, fees
Staking/Vaults	Deposit/withdraw, rewards, share accounting
NFT/Gaming	Minting, randomness, marketplace
Governance	Voting, timelock, proposal execution

Output Structure

# [Project Name] Overview

## Summary
[2-3 sentences: what does this project do?]

## Architecture
- Contract list with purpose
- Key inheritance (ERC4626, Ownable, etc.)
- External dependencies

## Entry Points

### User Functions (Priority: High)
| Function | Contract | Risk |
|----------|----------|------|
| deposit() | Vault.sol:45 | Handles ETH |
| withdraw() | Vault.sol:89 | Sends ETH |

### Admin Functions (Check Access Control)
| Function | Contract | Permission |
|----------|----------|------------|
| setFee() | Vault.sol:120 | onlyOwner |

### Callbacks (Reentrancy Risk)
- onFlashLoan() called by flash lender

## Value Flow
- **In:** ETH via deposit(), tokens via depositToken()
- **Out:** ETH via withdraw(), rewards via claim()

## Trust Model
- **Owner:** Can pause, set fees (max X%)
- **External:** Chainlink oracle (single price feed)

## Audit Focus (Prioritized)
1. [High] Reentrancy in withdraw() - external call before state update
2. [High] Oracle manipulation - single feed, no TWAP
3. [Med] Share inflation - first depositor attack?

## Recommended Audit Order
1. Vault.sol - core logic, highest risk
2. Router.sol - entry point, input validation
3. Token.sol - standard ERC20, lower priority

After Overview

Offer:

• "Run Weasel static analysis?"
• "Deep dive into [highest risk contract]?"
• "Explain specific function?"

Rationalizations to Reject

Rationalization	Why It's Wrong
"I'll skip the libraries, they're standard"	Libraries can be modified or misused. Note them.
"This looks like a simple project"	Simple projects can have complex bugs. Be thorough.
"README explains everything"	README can be outdated. Verify against actual code.
"I'll focus only on the main contract"	Entry points can be anywhere. Map ALL external functions.
"Previous audit means it's safe"	Previous audits miss things. Note them, don't rely on them.
"I understand the pattern, no need to map it"	Every implementation differs. Map THIS codebase.