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!
1---2name: guidelines-advisor3description: 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.4metadata:5 source: https://skillmd.com/skills/trailofbits/guidelines-advisor6---78# Guidelines Advisor910## Purpose1112Systematically analyzes the codebase and provides guidance based on Trail of Bits' development guidelines:13141. **Generate documentation and specifications** (plain English descriptions, architectural diagrams, code documentation)152. **Optimize on-chain/off-chain architecture** (only if applicable)163. **Review upgradeability patterns** (if your project has upgrades)174. **Check delegatecall/proxy implementations** (if present)185. **Assess implementation quality** (functions, inheritance, events)196. **Identify common pitfalls**207. **Review dependencies**218. **Evaluate test suite and suggest improvements**2223**Framework**: Building Secure Contracts - Development Guidelines2425---2627## How This Works2829### Phase 1: Discovery & Context30Explores the codebase to understand:31- Project structure and platform32- Contract/module files and their purposes33- Existing documentation34- Architecture patterns (proxies, upgrades, etc.)35- Testing setup36- Dependencies3738### Phase 2: Documentation Generation39Helps create:40- Plain English system description41- Architectural diagrams (using Slither printers for Solidity)42- Code documentation recommendations (NatSpec for Solidity)4344### Phase 3: Architecture Analysis45Analyzes:46- On-chain vs off-chain component distribution (if applicable)47- Upgradeability approach (if applicable)48- Delegatecall proxy patterns (if present)4950### Phase 4: Implementation Review51Assesses:52- Function composition and clarity53- Inheritance structure54- Event logging practices55- Common pitfalls presence56- Dependencies quality57- Testing coverage and techniques5859### Phase 5: Recommendations60Provides:61- Prioritized improvement suggestions62- Best practice guidance63- Actionable next steps6465---6667## Assessment Areas6869I 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).7071### Quick Reference:72731. **Documentation & Specifications**74 - Plain English system descriptions75 - Architectural diagrams76 - NatSpec completeness (Solidity)77 - Documentation gaps identification78792. **On-Chain vs Off-Chain Computation**80 - Complexity analysis81 - Gas optimization opportunities82 - Verification vs computation patterns83843. **Upgradeability**85 - Migration vs upgradeability trade-offs86 - Data separation patterns87 - Upgrade procedure documentation88894. **Delegatecall Proxy Pattern**90 - Storage layout consistency91 - Initialization patterns92 - Function shadowing risks93 - Slither upgradeability checks94955. **Function Composition**96 - Function size and clarity97 - Logical grouping98 - Modularity assessment991006. **Inheritance**101 - Hierarchy depth/width102 - Diamond problem risks103 - Inheritance visualization1041057. **Events**106 - Critical operation coverage107 - Event naming consistency108 - Indexed parameters1091108. **Common Pitfalls**111 - Reentrancy patterns112 - Integer overflow/underflow113 - Access control issues114 - Platform-specific vulnerabilities1151169. **Dependencies**117 - Library quality assessment118 - Version management119 - Dependency manager usage120 - Copied code detection12112210. **Testing & Verification**123 - Coverage analysis124 - Fuzzing techniques125 - Formal verification126 - CI/CD integration12712811. **Platform-Specific Guidance**129 - Solidity version recommendations130 - Compiler warning checks131 - Inline assembly warnings132 - Platform-specific tools133134For complete details on each area including what I'll check, analyze, and recommend, see [ASSESSMENT_AREAS.md](resources/ASSESSMENT_AREAS.md).135136---137138## Example Output139140When the analysis is complete, you'll receive comprehensive guidance covering:141142- System documentation with plain English descriptions143- Architectural diagrams and documentation gaps144- Architecture analysis (on-chain/off-chain, upgradeability, proxies)145- Implementation review (functions, inheritance, events, pitfalls)146- Dependencies and testing evaluation147- Prioritized recommendations (CRITICAL, HIGH, MEDIUM, LOW)148- Overall assessment and path to production149150For a complete example analysis report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md).151152---153154## Deliverables155156I provide four comprehensive deliverable categories:157158### 1. System Documentation159- Plain English descriptions160- Architectural diagrams161- Documentation gaps analysis162163### 2. Architecture Analysis164- On-chain/off-chain assessment165- Upgradeability review166- Proxy pattern security review167168### 3. Implementation Review169- Function composition analysis170- Inheritance assessment171- Events coverage172- Pitfall identification173- Dependencies evaluation174- Testing analysis175176### 4. Prioritized Recommendations177- CRITICAL (address immediately)178- HIGH (address before deployment)179- MEDIUM (address for production quality)180- LOW (nice to have)181182For detailed templates and examples of each deliverable, see [DELIVERABLES.md](resources/DELIVERABLES.md).183184---185186## Assessment Process187188When invoked, I will:1891901. **Explore the codebase**191 - Identify all contract/module files192 - Find existing documentation193 - Locate test files194 - Check for proxies/upgrades195 - Identify dependencies1961972. **Generate documentation**198 - Create plain English system description199 - Generate architectural diagrams (if tools available)200 - Identify documentation gaps2012023. **Analyze architecture**203 - Assess on-chain/off-chain distribution (if applicable)204 - Review upgradeability approach (if applicable)205 - Audit proxy patterns (if present)2062074. **Review implementation**208 - Analyze functions, inheritance, events209 - Check for common pitfalls210 - Assess dependencies211 - Evaluate testing2122135. **Provide recommendations**214 - Present findings with file references215 - Ask clarifying questions about design decisions216 - Suggest prioritized improvements217 - Offer actionable next steps218219---220221## Rationalizations (Do Not Skip)222223| Rationalization | Why It's Wrong | Required Action |224|-----------------|----------------|-----------------|225| "System is simple, description covers everything" | Plain English descriptions miss security-critical details | Complete all 5 phases: documentation, architecture, implementation, dependencies, recommendations |226| "No upgrades detected, skip upgradeability section" | Upgradeability can be implicit (ownable patterns, delegatecall) | Search for proxy patterns, delegatecall, storage collisions before declaring N/A |227| "Not applicable" without verification | Premature scope reduction misses vulnerabilities | Verify with explicit codebase search before skipping any guideline section |228| "Architecture is straightforward, no analysis needed" | Obvious architectures have subtle trust boundaries | Analyze on-chain/off-chain distribution, access control flow, external dependencies |229| "Common pitfalls don't apply to this codebase" | Every codebase has common pitfalls | Systematically check all guideline pitfalls with grep/code search |230| "Tests exist, testing guideline is satisfied" | Test existence ≠ test quality | Check coverage, property-based tests, integration tests, failure cases |231| "I can provide generic best practices" | Generic advice isn't actionable | Provide project-specific findings with file:line references |232| "User knows what to improve from findings" | Findings without prioritization = no action plan | Generate prioritized improvement roadmap with specific next steps |233234---235236## Notes237238- I'll only analyze relevant sections (won't hallucinate about upgrades if not present)239- I'll adapt to your platform (Solidity, Rust, Cairo, etc.)240- I'll use available tools (Slither, etc.) but work without them if unavailable241- I'll provide file references and line numbers for all findings242- I'll ask questions about design decisions I can't infer from code243244---245246## Ready to Begin247248**What I'll need**:249- Access to your codebase250- Context about your project goals251- Any existing documentation or specifications252- Information about deployment plans253254Let's analyze your codebase and improve it using Trail of Bits' best practices!