guidelines-advisor

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

1. On-Chain vs Off-Chain Computation

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

1. Upgradeability

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

1. Delegatecall Proxy Pattern

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

1. Function Composition

• Function size and clarity
• Logical grouping
• Modularity assessment

1. Inheritance

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

1. Events

• Critical operation coverage
• Event naming consistency
• Indexed parameters

1. Common Pitfalls

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

1. Dependencies

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

1. Testing & Verification

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

1. 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

1. Generate documentation

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

1. Analyze architecture

• Assess on-chain/off-chain distribution (if applicable)
• Review upgradeability approach (if applicable)
• Audit proxy patterns (if present)

1. Review implementation

• Analyze functions, inheritance, events
• Check for common pitfalls
• Assess dependencies
• Evaluate testing

1. 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!