/guidelines-advisor

name: guidelines-advisor
description: 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. Use when asking whether a smart contract project follows development best practices, reviewing on-chain/off-chain split, upgradeability, or delegatecall proxy patterns against guidelines, or seeking recommendations on contract design, inheritance, events, documentation, dependencies, or test strategy.

Guidelines Advisor

Purpose

Systematically analyzes the codebase and provides guidance based on Trail of Bits' development guidelines:

1. **Generate documentation and specifications** (plain English descriptions, architectural diagrams, code documentation) 2. **Optimize on-chain/off-chain architecture** (only if applicable) 3. **Review upgradeability patterns** (if your project has upgrades) 4. **Check delegatecall/proxy implementations** (if present) 5. **Assess implementation quality** (functions, inheritance, events) 6. **Identify common pitfalls** 7. **Review dependencies** 8. **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](resources/ASSESSMENT_AREAS.md).

Quick Reference:

1. **Documentation & Specifications**

• Plain English system descriptions
• Architectural diagrams
• NatSpec completeness (Solidity)
• Documentation gaps identification

2. **On-Chain vs Off-Chain Computation**

• Complexity analysis
• Gas optimization opportunities
• Verification vs computation patterns

3. **Upgradeability**

• Migration vs upgradeability trade-offs
• Data separation patterns
• Upgrade procedure documentation

4. **Delegatecall Proxy Pattern**

• Storage layout consistency
• Initialization patterns
• Function shadowing risks
• Slither upgradeability checks

5. **Function Composition**

• Function size and clarity
• Logical grouping
• Modularity assessment

6. **Inheritance**

• Hierarchy depth/width
• Diamond problem risks
• Inheritance visualization

7. **Events**

• Critical operation coverage
• Event naming consistency
• Indexed parameters

8. **Common Pitfalls**

• Reentrancy patterns
• Integer overflow/underflow
• Access control issues
• Platform-specific vulnerabilities

9. **Dependencies**

• Library quality assessment
• Version management
• Dependency manager usage
• Copied code detection

10. **Testing & Verification**

• Coverage analysis
• Fuzzing techniques
• Formal verification
• CI/CD integration

11. **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](resources/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](resources/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](resources/DELIVERABLES.md).

---

Assessment Process

When invoked, I will:

1. **Explore the codebase**

• Identify all contract/module files
• Find existing documentation
• Locate test files
• Check for proxies/upgrades
• Identify dependencies

2. **Generate documentation**

• Create plain English system description
• Generate architectural diagrams (if tools available)
• Identify d