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!
Source: trailofbits/skills → plugins/building-secure-contracts/skills/guidelines-advisor/SKILL.md
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."4category: engineering-core5source_repo: trailofbits/skills6source_path: "plugins/building-secure-contracts/skills/guidelines-advisor/SKILL.md"7source_url: https://github.com/trailofbits/skills/blob/HEAD/plugins/building-secure-contracts/skills/guidelines-advisor/SKILL.md8metadata:9 source: https://skillmd.com/skills/thedixitjain/guidelines-advisor10---111213# Guidelines Advisor1415## Purpose1617Systematically analyzes the codebase and provides guidance based on Trail of Bits' development guidelines:18191. **Generate documentation and specifications** (plain English descriptions, architectural diagrams, code documentation)202. **Optimize on-chain/off-chain architecture** (only if applicable)213. **Review upgradeability patterns** (if your project has upgrades)224. **Check delegatecall/proxy implementations** (if present)235. **Assess implementation quality** (functions, inheritance, events)246. **Identify common pitfalls**257. **Review dependencies**268. **Evaluate test suite and suggest improvements**2728**Framework**: Building Secure Contracts - Development Guidelines2930---3132## How This Works3334### Phase 1: Discovery & Context35Explores the codebase to understand:36- Project structure and platform37- Contract/module files and their purposes38- Existing documentation39- Architecture patterns (proxies, upgrades, etc.)40- Testing setup41- Dependencies4243### Phase 2: Documentation Generation44Helps create:45- Plain English system description46- Architectural diagrams (using Slither printers for Solidity)47- Code documentation recommendations (NatSpec for Solidity)4849### Phase 3: Architecture Analysis50Analyzes:51- On-chain vs off-chain component distribution (if applicable)52- Upgradeability approach (if applicable)53- Delegatecall proxy patterns (if present)5455### Phase 4: Implementation Review56Assesses:57- Function composition and clarity58- Inheritance structure59- Event logging practices60- Common pitfalls presence61- Dependencies quality62- Testing coverage and techniques6364### Phase 5: Recommendations65Provides:66- Prioritized improvement suggestions67- Best practice guidance68- Actionable next steps6970---7172## Assessment Areas7374I 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).7576### Quick Reference:77781. **Documentation & Specifications**79 - Plain English system descriptions80 - Architectural diagrams81 - NatSpec completeness (Solidity)82 - Documentation gaps identification83842. **On-Chain vs Off-Chain Computation**85 - Complexity analysis86 - Gas optimization opportunities87 - Verification vs computation patterns88893. **Upgradeability**90 - Migration vs upgradeability trade-offs91 - Data separation patterns92 - Upgrade procedure documentation93944. **Delegatecall Proxy Pattern**95 - Storage layout consistency96 - Initialization patterns97 - Function shadowing risks98 - Slither upgradeability checks991005. **Function Composition**101 - Function size and clarity102 - Logical grouping103 - Modularity assessment1041056. **Inheritance**106 - Hierarchy depth/width107 - Diamond problem risks108 - Inheritance visualization1091107. **Events**111 - Critical operation coverage112 - Event naming consistency113 - Indexed parameters1141158. **Common Pitfalls**116 - Reentrancy patterns117 - Integer overflow/underflow118 - Access control issues119 - Platform-specific vulnerabilities1201219. **Dependencies**122 - Library quality assessment123 - Version management124 - Dependency manager usage125 - Copied code detection12612710. **Testing & Verification**128 - Coverage analysis129 - Fuzzing techniques130 - Formal verification131 - CI/CD integration13213311. **Platform-Specific Guidance**134 - Solidity version recommendations135 - Compiler warning checks136 - Inline assembly warnings137 - Platform-specific tools138139For complete details on each area including what I'll check, analyze, and recommend, see [ASSESSMENT_AREAS.md](resources/ASSESSMENT_AREAS.md).140141---142143## Example Output144145When the analysis is complete, you'll receive comprehensive guidance covering:146147- System documentation with plain English descriptions148- Architectural diagrams and documentation gaps149- Architecture analysis (on-chain/off-chain, upgradeability, proxies)150- Implementation review (functions, inheritance, events, pitfalls)151- Dependencies and testing evaluation152- Prioritized recommendations (CRITICAL, HIGH, MEDIUM, LOW)153- Overall assessment and path to production154155For a complete example analysis report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md).156157---158159## Deliverables160161I provide four comprehensive deliverable categories:162163### 1. System Documentation164- Plain English descriptions165- Architectural diagrams166- Documentation gaps analysis167168### 2. Architecture Analysis169- On-chain/off-chain assessment170- Upgradeability review171- Proxy pattern security review172173### 3. Implementation Review174- Function composition analysis175- Inheritance assessment176- Events coverage177- Pitfall identification178- Dependencies evaluation179- Testing analysis180181### 4. Prioritized Recommendations182- CRITICAL (address immediately)183- HIGH (address before deployment)184- MEDIUM (address for production quality)185- LOW (nice to have)186187For detailed templates and examples of each deliverable, see [DELIVERABLES.md](resources/DELIVERABLES.md).188189---190191## Assessment Process192193When invoked, I will:1941951. **Explore the codebase**196 - Identify all contract/module files197 - Find existing documentation198 - Locate test files199 - Check for proxies/upgrades200 - Identify dependencies2012022. **Generate documentation**203 - Create plain English system description204 - Generate architectural diagrams (if tools available)205 - Identify documentation gaps2062073. **Analyze architecture**208 - Assess on-chain/off-chain distribution (if applicable)209 - Review upgradeability approach (if applicable)210 - Audit proxy patterns (if present)2112124. **Review implementation**213 - Analyze functions, inheritance, events214 - Check for common pitfalls215 - Assess dependencies216 - Evaluate testing2172185. **Provide recommendations**219 - Present findings with file references220 - Ask clarifying questions about design decisions221 - Suggest prioritized improvements222 - Offer actionable next steps223224---225226## Rationalizations (Do Not Skip)227228| Rationalization | Why It's Wrong | Required Action |229|-----------------|----------------|-----------------|230| "System is simple, description covers everything" | Plain English descriptions miss security-critical details | Complete all 5 phases: documentation, architecture, implementation, dependencies, recommendations |231| "No upgrades detected, skip upgradeability section" | Upgradeability can be implicit (ownable patterns, delegatecall) | Search for proxy patterns, delegatecall, storage collisions before declaring N/A |232| "Not applicable" without verification | Premature scope reduction misses vulnerabilities | Verify with explicit codebase search before skipping any guideline section |233| "Architecture is straightforward, no analysis needed" | Obvious architectures have subtle trust boundaries | Analyze on-chain/off-chain distribution, access control flow, external dependencies |234| "Common pitfalls don't apply to this codebase" | Every codebase has common pitfalls | Systematically check all guideline pitfalls with grep/code search |235| "Tests exist, testing guideline is satisfied" | Test existence ≠ test quality | Check coverage, property-based tests, integration tests, failure cases |236| "I can provide generic best practices" | Generic advice isn't actionable | Provide project-specific findings with file:line references |237| "User knows what to improve from findings" | Findings without prioritization = no action plan | Generate prioritized improvement roadmap with specific next steps |238239---240241## Notes242243- I'll only analyze relevant sections (won't hallucinate about upgrades if not present)244- I'll adapt to your platform (Solidity, Rust, Cairo, etc.)245- I'll use available tools (Slither, etc.) but work without them if unavailable246- I'll provide file references and line numbers for all findings247- I'll ask questions about design decisions I can't infer from code248249---250251## Ready to Begin252253**What I'll need**:254- Access to your codebase255- Context about your project goals256- Any existing documentation or specifications257- Information about deployment plans258259Let's analyze your codebase and improve it using Trail of Bits' best practices!260261---262263**Source:** [`trailofbits/skills`](https://github.com/trailofbits/skills) → `plugins/building-secure-contracts/skills/guidelines-advisor/SKILL.md`