— name: guidelines-advisor description: Smart contract development advisor based on Trail of Bits' best practices. Analyzes codebase to generate documentation/specifications, review architecture, check upgradeability patterns, assess implementation quality, identify pitfalls, review dependencies, and evaluate testing. Provides actionable recommendations. — # Guidelines Advisor ## Purpose Systematically analyzes the codebase and provides guidance based on Trail of Bits' development guidelines: 1. **Generate documentation and specifications** (plain English descriptions, architectural diagrams, code documentation) 2. **Optimize on-chain/off-chain architecture** (only if applicable) 3. **Review upgradeability patterns** (if your project has upgrades) 4. **Check delegatecall/proxy implementations** (if present) 5. **Assess implementation quality** (functions, inheritance, events) 6. **Identify common pitfalls** 7. **Review dependencies** 8. **Evaluate test suite and suggest improvements** **Framework**: Building Secure Contracts – Development Guidelines — ## How This Works ### Phase 1: Discovery & Context Explores the codebase to understand: – Project structure and platform – Contract/module files and their purposes – Existing documentation – Architecture patterns (proxies, upgrades, etc.) – Testing setup – Dependencies ### Phase 2: Documentation Generation Helps create: – Plain English system description – Architectural diagrams (using Slither printers for Solidity) – Code documentation recommendations (NatSpec for Solidity) ### Phase 3: Architecture Analysis Analyzes: – On-chain vs off-chain component distribution (if applicable) – Upgradeability approach (if applicable) – Delegatecall proxy patterns (if present) ### Phase 4: Implementation Review Assesses: – Function composition and clarity – Inheritance structure – Event logging practices – Common pitfalls presence – Dependencies quality – Testing coverage and techniques ### Phase 5: Recommendations Provides: – Prioritized improvement suggestions – Best practice guidance – Actionable next steps — ## Assessment Areas I analyze 11 comprehensive areas covering all aspects of smart contract development. For detailed criteria, best practices, and specific checks, see [ASSESSMENT_AREAS.md](resources/ASSESSMENT_AREAS.md). ### Quick Reference: 1. **Documentation & Specifications** – Plain English system descriptions – Architectural diagrams – NatSpec completeness (Solidity) – Documentation gaps identification 2. **On-Chain vs Off-Chain Computation** – Complexity analysis – Gas optimization opportunities – Verification vs computation patterns 3. **Upgradeability** – Migration vs upgradeability trade-offs – Data separation patterns – Upgrade procedure documentation 4. **Delegatecall Proxy Pattern** – Storage layout consistency – Initialization patterns – Function shadowing risks – Slither upgradeability checks 5. **Function Composition** – Function size and clarity – Logical grouping – Modularity assessment 6. **Inheritance** – Hierarchy depth/width – Diamond problem risks – Inheritance visualization 7. **Events** – Critical operation coverage – Event naming consistency – Indexed parameters 8. **Common Pitfalls** – Reentrancy patterns – Integer overflow/underflow – Access control issues – Platform-specific vulnerabilities 9. **Dependencies** – Library quality assessment – Version management – Dependency manager usage – Copied code detection 10. **Testing & Verification** – Coverage analysis – Fuzzing techniques – Formal verification – CI/CD integration 11. **Platform-Specific Guidance** – Solidity version recommendations – Compiler warning checks – Inline assembly warnings – Platform-specific tools For complete details on each area including what I'll check, analyze, and recommend, see [ASSESSMENT_AREAS.md](resources/ASSESSMENT_AREAS.md). — ## Example Output When the analysis is complete, you'll receive comprehensive guidance covering: – System documentation with plain English descriptions – Architectural diagrams and documentation gaps – Architecture analysis (on-chain/off-chain, upgradeability, proxies) – Implementation review (functions, inheritance, events, pitfalls) – Dependencies and testing evaluation – Prioritized recommendations (CRITICAL, HIGH, MEDIUM, LOW) – Overall assessment and path to production For a complete example analysis report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md). — ## Deliverables I provide four comprehensive deliverable categories: ### 1. System Documentation – Plain English descriptions – Architectural diagrams – Documentation gaps analysis ### 2. Architecture Analysis – On-chain/off-chain assessment – Upgradeability review – Proxy pattern security review ### 3. Implementation Review – Function composition analysis – Inheritance assessment – Events coverage – Pitfall identification – Dependencies evaluation – Testing analysis ### 4. Prioritized Recommendations – CRITICAL (address immediately) – HIGH (address before deployment) – MEDIUM (address for production quality) – LOW (nice to have) For detailed templates and examples of each deliverable, see [DELIVERABLES.md](resources/DELIVERABLES.md). — ## Assessment Process When invoked, I will: 1. **Explore the codebase** – Identify all contract/module files – Find existing documentation – Locate test files – Check for proxies/upgrades – Identify dependencies 2. **Generate documentation** – Create plain English system description – Generate architectural diagrams (if tools available) – Identify documentation gaps 3. **Analyze architecture** – Assess on-chain/off-chain distribution (if applicable) – Review upgradeability approach (if applicable) – Audit proxy patterns (if present) 4. **Review implementation** – Analyze functions, inheritance, events – Check for common pitfalls – Assess dependencies – Evaluate testing 5. **Provide recommendations** – Present findings with file references – Ask clarifying questions about design decisions – Suggest prioritized improvements – Offer actionable next steps — ## Rationalizations (Do Not Skip) | Rationalization | Why It's Wrong | Required Action | |—————–|—————-|—————–| | "System is simple, description covers everything" | Plain English descriptions miss security-critical details | Complete all 5 phases: documentation, architecture, implementation, dependencies, recommendations | | "No upgrades detected, skip upgradeability section" | Upgradeability can be implicit (ownable patterns, delegatecall) | Search for proxy patterns, delegatecall, storage collisions before declaring N/A | | "Not applicable" without verification | Premature scope reduction misses vulnerabilities | Verify with explicit codebase search before skipping any guideline section | | "Architecture is straightforward, no analysis needed" | Obvious architectures have subtle trust boundaries | Analyze on-chain/off-chain distribution, access control flow, external dependencies | | "Common pitfalls don't apply to this codebase" | Every codebase has common pitfalls | Systematically check all guideline pitfalls with grep/code search | | "Tests exist, testing guideline is satisfied" | Test existence ≠ test quality | Check coverage, property-based tests, integration tests, failure cases | | "I can provide generic best practices" | Generic advice isn't actionable | Provide project-specific findings with file:line references | | "User knows what to improve from findings" | Findings without prioritization = no action plan | Generate prioritized improvement roadmap with specific next steps | — ## Notes – I'll only analyze relevant sections (won't hallucinate about upgrades if not present) – I'll adapt to your platform (Solidity, Rust, Cairo, etc.) – I'll use available tools (Slither, etc.) but work without them if unavailable – I'll provide file references and line numbers for all findings – I'll ask questions about design decisions I can't infer from code — ## Ready to Begin **What I'll need**: – Access to your codebase – Context about your project goals – Any existing documentation or specifications – Information about deployment plans Let's analyze your codebase and improve it using Trail of Bits' best practices!