docs-analysis

# Documentation Reconnaissance Methodology ## Purpose Rapidly understand **what the protocol should do** through documentation analysis. This is reconnaissance, not code analysis. --- ## 1. Documentation Discovery ### Search Patterns ``` Glob("**/README*") Glob("**/*.md") Glob("**/docs/**/*") Glob("**/SECURITY*") Glob("**/*.pdf") ``` ### Priority Order | Priority | File | What to Extract | |----------|------|-----------------| | 1 | Root README | Project overview, quick start | | 2 | docs/README.md | Documentation entry point | | 3 | SECURITY.md | Security considerations, contacts | | 4 | Whitepaper/spec | Formal specification | | 5 | Audit reports | Known issues, past findings | ### Skip These - Code files (`.sol`, `.rs`, etc.) - Test documentation - CI/CD configuration --- ## 2. The 4 Essential Questions ### Question 1: Where Is the Money? | Asset Type | What to Look For | |------------|------------------| | Native tokens | ETH, MATIC, AVAX holdings | | ERC20 tokens | USDC, USDT, DAI, protocol tokens | | LP tokens | Uniswap, Curve, Balancer positions | | NFTs | ERC721, ERC1155 assets | | Shares/receipts | Vault shares, staked positions | **Extract**: Which contracts hold assets, TVL mentions, treasury. ### Question 2: Who Can Move the Money? **User Paths**: | Action | Function Names | |--------|---------------| | Deposit | `deposit()`, `stake()`, `supply()`, `mint()` | | Withdraw | `withdraw()`, `unstake()`, `redeem()`, `burn()` | **Privileged Paths**: | Action | Function Names | Risk Level | |--------|---------------|------------| | Emergency | `emergencyWithdraw()`, `pause()` | High | | Recovery | `sweep()`, `rescue()`, `skim()` | High | | Config | `setFee()`, `setOracle()`, `upgradeTo()` | Medium | **Extract**: Function names, who can call, conditions. ### Question 3: What Invariants Must Hold? **Explicit Invariants** - Keywords: - "must", "always", "never", "guaranteed", "ensures" - Mathematical relationships: `x + y = z`, `a <= b * c` - NatSpec: `@invariant`, `@notice` **Implicit Invariants** - By Protocol Type: | Protocol Type | Common Invariant | |---------------|------------------| | Vault | `totalAssets >= totalShares * minPrice` | | Lending | `userDebt <= userCollateral * LTV` | | AMM | `reserveX * reserveY >= k` | | Staking | `sum(userStakes) == totalStaked` | | Bridge | `mintedOnL2 == lockedOnL1` | Mark inferred invariants with `[INFERRED]`. ### Question 4: What Trust Assumptions Exist? | Trusted Party | What They Control | Questions to Answer | |--------------|-------------------|---------------------| | Owner | Contract upgrades | Timelock? Multisig? | | Admin | Parameter changes | Bounds? Frequency? | | Oracle | Price feeds | Freshness? Backup? | | Keeper | Liquidations | Incentives? Constraints? | **Extract**: Who is trusted, for what, with what safeguards. --- ## 3. Protocol Type Classification | Pattern in Docs | Protocol Type | Priority Vectors | |-----------------|---------------|------------------| | swap, liquidity, reserves | AMM/DEX | Price manipulation, sandwich | | borrow, collateral, liquidate | Lending | Oracle manipulation, bad debt | | deposit, shares, yield | Vault | Share inflation, first depositor | | vote, propose, execute | Governance | Flash loan voting, timelock | | lock, mint, bridge | Bridge | Double spend, replay | | stake, reward, epoch | Staking | Reward calculation, timing | --- ## 4. Extraction Process ### Step 1: High-Level Understanding Read overview documents to understand: - Protocol purpose and value proposition - Target users and use cases - Integration with other protocols - Economic model ### Step 2: Mechanism Analysis For each mechanism described: 1. Identify inputs and outputs 2. Note preconditions and postconditions 3. Extract mathematical relationships 4. Identify external dependencies ### Step 3: Security Information Look for: - Security considerations sections - Known limitations and risks - Threat model descriptions - Emergency procedures ### Step 4: Gap Identification Note what's MISSING: - Undefined edge cases - Unclear trust assumptions - Missing invariants - Ambiguous specifications --- ## 5. Quality Assessment | Rating | Criteria | |--------|----------| | Excellent | Complete invariants, clear trust model, all mechanisms documented | | Good | Most information present, some inference needed | | Adequate | Basic coverage, significant gaps | | Poor | Minimal documentation, heavy inference required | | Minimal | Almost no documentation | --- ## 6. Edge Cases ### Minimal Documentation 1. Note quality as "Poor" or "Minimal" 2. Flag ALL missing critical information 3. Infer what possible, mark as `[INFERRED]` 4. Recommend documentation improvements 5. Note increased audit risk ### Conflicting Information 1. Note the conflict explicitly 2. List all versions found 3. Flag for clarification 4. Do not assume which is correct ### Non-English Documentation 1. Note the language limitation 2. Extract what is possible 3. Flag for native speaker review --- ## Output Write findings to `.vigilo/recon/docs-findings.md` following the format in [`template.md`](template.md). --- ## Additional Resources - [**`template.md`**](template.md) - Output template for documentation reconnaissance findings - [**`examples/minimal-output.md`**](examples/minimal-output.md) - Minimal output example for sparse documentation