| name | guidelines-advisor |
| description | Comprehensive 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 examine codebases to provide guidance on:
- Generating documentation and specifications
- Optimizing on-chain/off-chain architecture
- Reviewing upgradeability patterns
- Checking delegatecall/proxy implementations
- Assessing implementation quality
- Identifying common pitfalls
- Reviewing dependencies
- Evaluating test suites
Framework: Building Secure Contracts - Development Guidelines
How This Works
Phase 1: Discovery & Context
Explores project structure, contract files, existing documentation, architecture patterns, testing setup, and dependencies.
Phase 2: Documentation Generation
Creates plain English system descriptions, architectural diagrams, and NatSpec completeness recommendations.
Phase 3: Architecture Analysis
Analyzes on-chain/off-chain distribution, upgradeability approaches, and proxy patterns.
Phase 4: Implementation Review
Assesses function composition, inheritance structure, event logging, common pitfalls, dependencies, and testing coverage.
Phase 5: Recommendations
Presents prioritized improvement suggestions, best practices, and actionable next steps.
Assessment Areas
Analyzes 11 comprehensive areas:
- Documentation & Specifications: Plain English descriptions, architectural diagrams, NatSpec completeness
- On-Chain vs Off-Chain Computation: Complexity analysis, gas optimization, verification patterns
- Upgradeability: Migration vs upgradeability trade-offs, data separation, upgrade procedures
- Delegatecall Proxy Pattern: Storage layout consistency, initialization patterns, function shadowing risks
- Function Composition: Function size, logical grouping, modularity assessment
- Inheritance: Hierarchy depth/width, diamond problem risks, visualization
- Events: Critical operation coverage, naming consistency, indexed parameters
- Common Pitfalls: Reentrancy, integer overflow/underflow, access control issues
- Dependencies: Library quality, version management, copied code detection
- Testing & Verification: Coverage analysis, fuzzing, formal verification, CI/CD integration
- Platform-Specific Guidance: Solidity version recommendations, compiler warnings, inline assembly
Deliverables
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)
Assessment Process
- Explore the codebase: Identify files, documentation, tests, proxies, dependencies
- Generate documentation: Create descriptions, diagrams, identify gaps
- Analyze architecture: Assess distribution, upgradeability, proxy patterns
- Review implementation: Analyze functions, inheritance, events, pitfalls, dependencies, testing
- Provide recommendations: Present findings with file references, ask design questions, suggest improvements, outline 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 |
| "No upgrades detected, skip upgradeability section" | Upgradeability can be implicit (ownable patterns, delegatecall) | Search for proxy patterns before declaring N/A |
| "Not applicable" without verification | Premature scope reduction misses vulnerabilities | Verify with explicit codebase search |
| "Architecture is straightforward, no analysis needed" | Obvious architectures have subtle trust boundaries | Analyze on-chain/off-chain distribution, access control |
| "Common pitfalls don't apply to this codebase" | Every codebase has common pitfalls | Systematically check all guideline pitfalls |
| "Tests exist, testing guideline is satisfied" | Test existence != test quality | Check coverage, property-based tests, integration tests |
| "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 |
Notes
- Only analyzes relevant sections; won't hallucinate about absent features
- Adapts to platform (Solidity, Rust, Cairo, etc.)
- Uses available tools but works without them
- Provides file references and line numbers for all findings
- Asks questions about design decisions inferred from code
Ready to Begin
What I'll need:
- Access to your codebase
- Context about project goals
- Existing documentation or specifications
- Information about deployment plans
