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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: guidelines-advisor-23description: 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. Use when this capability is needed.4---56# Guidelines Advisor78## Purpose910Systematically examine codebases to provide guidance on:11121. Generating documentation and specifications132. Optimizing on-chain/off-chain architecture143. Reviewing upgradeability patterns154. Checking delegatecall/proxy implementations165. Assessing implementation quality176. Identifying common pitfalls187. Reviewing dependencies198. Evaluating test suites2021**Framework**: Building Secure Contracts - Development Guidelines2223---2425## How This Works2627### Phase 1: Discovery & Context2829Explores project structure, contract files, existing documentation, architecture patterns, testing setup, and dependencies.3031### Phase 2: Documentation Generation3233Creates plain English system descriptions, architectural diagrams, and NatSpec completeness recommendations.3435### Phase 3: Architecture Analysis3637Analyzes on-chain/off-chain distribution, upgradeability approaches, and proxy patterns.3839### Phase 4: Implementation Review4041Assesses function composition, inheritance structure, event logging, common pitfalls, dependencies, and testing coverage.4243### Phase 5: Recommendations4445Presents prioritized improvement suggestions, best practices, and actionable next steps.4647---4849## Assessment Areas5051Analyzes 11 comprehensive areas:52531. **Documentation & Specifications**: Plain English descriptions, architectural diagrams, NatSpec completeness542. **On-Chain vs Off-Chain Computation**: Complexity analysis, gas optimization, verification patterns553. **Upgradeability**: Migration vs upgradeability trade-offs, data separation, upgrade procedures564. **Delegatecall Proxy Pattern**: Storage layout consistency, initialization patterns, function shadowing risks575. **Function Composition**: Function size, logical grouping, modularity assessment586. **Inheritance**: Hierarchy depth/width, diamond problem risks, visualization597. **Events**: Critical operation coverage, naming consistency, indexed parameters608. **Common Pitfalls**: Reentrancy, integer overflow/underflow, access control issues619. **Dependencies**: Library quality, version management, copied code detection6210. **Testing & Verification**: Coverage analysis, fuzzing, formal verification, CI/CD integration6311. **Platform-Specific Guidance**: Solidity version recommendations, compiler warnings, inline assembly6465---6667## Deliverables6869### 1. System Documentation7071- Plain English descriptions72- Architectural diagrams73- Documentation gaps analysis7475### 2. Architecture Analysis7677- On-chain/off-chain assessment78- Upgradeability review79- Proxy pattern security review8081### 3. Implementation Review8283- Function composition analysis84- Inheritance assessment85- Events coverage86- Pitfall identification87- Dependencies evaluation88- Testing analysis8990### 4. Prioritized Recommendations9192- CRITICAL (address immediately)93- HIGH (address before deployment)94- MEDIUM (address for production quality)95- LOW (nice to have)9697---9899## Assessment Process1001011. **Explore the codebase**: Identify files, documentation, tests, proxies, dependencies1022. **Generate documentation**: Create descriptions, diagrams, identify gaps1033. **Analyze architecture**: Assess distribution, upgradeability, proxy patterns1044. **Review implementation**: Analyze functions, inheritance, events, pitfalls, dependencies, testing1055. **Provide recommendations**: Present findings with file references, ask design questions, suggest improvements, outline next steps106107---108109## Rationalizations (Do Not Skip)110111| Rationalization | Why It's Wrong | Required Action |112| ----------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------- |113| "System is simple, description covers everything" | Plain English descriptions miss security-critical details | Complete all 5 phases |114| "No upgrades detected, skip upgradeability section" | Upgradeability can be implicit (ownable patterns, delegatecall) | Search for proxy patterns before declaring N/A |115| "Not applicable" without verification | Premature scope reduction misses vulnerabilities | Verify with explicit codebase search |116| "Architecture is straightforward, no analysis needed" | Obvious architectures have subtle trust boundaries | Analyze on-chain/off-chain distribution, access control |117| "Common pitfalls don't apply to this codebase" | Every codebase has common pitfalls | Systematically check all guideline pitfalls |118| "Tests exist, testing guideline is satisfied" | Test existence != test quality | Check coverage, property-based tests, integration tests |119| "I can provide generic best practices" | Generic advice isn't actionable | Provide project-specific findings with file:line references |120| "User knows what to improve from findings" | Findings without prioritization = no action plan | Generate prioritized improvement roadmap |121122---123124## Notes125126- Only analyzes relevant sections; won't hallucinate about absent features127- Adapts to platform (Solidity, Rust, Cairo, etc.)128- Uses available tools but works without them129- Provides file references and line numbers for all findings130- Asks questions about design decisions inferred from code131132---133134## Ready to Begin135136**What I'll need**:137138- Access to your codebase139- Context about project goals140- Existing documentation or specifications141- Information about deployment plans142143---144> Converted and distributed by [TomeVault](https://tomevault.io/claim/towns-protocol) — claim your Tome and manage your conversions.145<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io