Guidelines Advisor
Purpose
Systematically analyzes the codebase and provides guidance based on Trail of Bits' development guidelines:
- Generate documentation and specifications (plain English descriptions, architectural diagrams, code documentation)
- Optimize on-chain/off-chain architecture (only if applicable)
- Review upgradeability patterns (if your project has upgrades)
- Check delegatecall/proxy implementations (if present)
- Assess implementation quality (functions, inheritance, events)
- Identify common pitfalls
- Review dependencies
- 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.
Quick Reference:
- Documentation & Specifications
- Plain English system descriptions - Architectural diagrams - NatSpec completeness (Solidity) - Documentation gaps identification
- On-Chain vs Off-Chain Computation
- Complexity analysis - Gas optimization opportunities - Verification vs computation patterns
- Upgradeability
- Migration vs upgradeability trade-offs - Data separation patterns - Upgrade procedure documentation
- Delegatecall Proxy Pattern
- Storage layout consistency - Initialization patterns - Function shadowing risks - Slither upgradeability checks
- Function Composition
- Function size and clarity - Logical grouping - Modularity assessment
- Inheritance
- Hierarchy depth/width - Diamond problem risks - Inheritance visualization
- Events
- Critical operation coverage - Event naming consistency - Indexed parameters
- Common Pitfalls
- Reentrancy patterns - Integer overflow/underflow - Access control issues - Platform-specific vulnerabilities
- Dependencies
- Library quality assessment - Version management - Dependency manager usage - Copied code detection
- Testing & Verification
- Coverage analysis - Fuzzing techniques - Formal verification - CI/CD integration
- 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.
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.
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.
Assessment Process
When invoked, I will:
- Explore the codebase
- Identify all contract/module files - Find existing documentation - Locate test files - Check for proxies/upgrades - Identify dependencies
- Generate documentation
- Create plain English system description - Generate architectural diagrams (if tools available) - Identify documentation gaps
- Analyze architecture
- Assess on-chain/off-chain distribution (if applicable) - Review upgradeability approach (if applicable) - Audit proxy patterns (if present)
- Review implementation
- Analyze functions, inheritance, events - Check for common pitfalls - Assess dependencies - Evaluate testing
- 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!