/code-maturity-assessor

name: code-maturity-assessor
description: Systematic code maturity assessment using Trail of Bits' 9-category framework. Analyzes codebase for arithmetic safety, auditing practices, access controls, complexity, decentralization, documentation, MEV risks, low-level code, and testing, then produces a scorecard with evidence-based ratings and a priority-ordered roadmap. Use when assessing or scoring the maturity of a smart contract or blockchain codebase, producing a maturity scorecard or evaluation, or judging how mature, well-tested, or well-documented such a project is against a rubric.

Code Maturity Assessor

Purpose

Systematically assesses codebase maturity using Trail of Bits' 9-category framework. Provides evidence-based ratings and actionable recommendations.

**Framework**: Building Secure Contracts - Code Maturity Evaluation v0.1.0

---

How This Works

Phase 1: Discovery

Explores the codebase to understand:

• Project structure and platform
• Contract/module files
• Test coverage
• Documentation availability

Phase 2: Analysis

For each of 9 categories, I'll:

• **Search the code** for relevant patterns
• **Read key files** to assess implementation
• **Present findings** with file references
• **Ask clarifying questions** about processes I can't see in code
• **Determine rating** based on criteria

Phase 3: Report

Generates:

• Executive summary
• Maturity scorecard (ratings for all 9 categories)
• Detailed analysis with evidence
• Priority-ordered improvement roadmap

---

Rating System

• **Missing (0)**: Not present/not implemented
• **Weak (1)**: Several significant improvements needed
• **Moderate (2)**: Adequate, can be improved
• **Satisfactory (3)**: Above average, minor improvements
• **Strong (4)**: Exceptional, only small improvements possible

**Rating Logic**:

• ANY "Weak" criteria → **Weak**
• NO "Weak" + SOME "Moderate" unmet → **Moderate**
• ALL "Moderate" + SOME "Satisfactory" met → **Satisfactory**
• ALL "Satisfactory" + exceptional practices → **Strong**

---

The 9 Categories

I assess 9 comprehensive categories covering all aspects of code maturity. For detailed criteria, analysis approaches, and rating thresholds, see [ASSESSMENT_CRITERIA.md](resources/ASSESSMENT_CRITERIA.md).

Quick Reference:

**1. ARITHMETIC**

• Overflow protection mechanisms
• Precision handling and rounding
• Formula specifications
• Edge case testing

**2. AUDITING**

• Event definitions and coverage
• Monitoring infrastructure
• Incident response planning

**3. AUTHENTICATION / ACCESS CONTROLS**

• Privilege management
• Role separation
• Access control testing
• Key compromise scenarios

**4. COMPLEXITY MANAGEMENT**

• Function scope and clarity
• Cyclomatic complexity
• Inheritance hierarchies
• Code duplication

**5. DECENTRALIZATION**

• Centralization risks
• Upgrade control mechanisms
• User opt-out paths
• Timelock/multisig patterns

**6. DOCUMENTATION**

• Specifications and architecture
• Inline code documentation
• User stories
• Domain glossaries

**7. TRANSACTION ORDERING RISKS**

• MEV vulnerabilities
• Front-running protections
• Slippage controls
• Oracle security

**8. LOW-LEVEL MANIPULATION**

• Assembly usage
• Unsafe code sections
• Low-level calls
• Justification and testing

**9. TESTING & VERIFICATION**

• Test coverage
• Fuzzing and formal verification
• CI/CD integration
• Test quality

For complete assessment criteria including what I'll analyze, what I'll ask you, and detailed rating thresholds (WEAK/MODERATE/SATISFACTORY/STRONG), see [ASSESSMENT_CRITERIA.md](resources/ASSESSMENT_CRITERIA.md).

---

Example Output

When the assessment is complete, you'll receive a comprehensive maturity report including:

• **Executive Summary**: Overall score, top 3 strengths, top 3 gaps, priority recommendations
• **Maturity Scorecard**: Table with all 9 categories rated with scores and notes
• **Detailed Analysis**: Category-by-category breakdown with evidence (file:line references)
• **Improvement Roadmap**: Priority-ordered recommendations (CRITICAL/HIGH/MEDIUM) with effort estimates

For a complete example assessment report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md).

---

Assessment Process

When invoked, I will:

1. **Explore codebase**

• Find contract/module files
• Identify test files
• Locate documentation

2. **Analyze each category**

• Search for relevant code patterns
• Read key implementations
• Assess against criteria
• Collect evidence

3. **Interactive assessment**

• Present my findings with file references
• Ask about processes I can't see in code
• Discuss borderline cases
• Determine ratings together

4. **Generate report**

• Executive summary
• Maturity scorecard table
• Detailed category analysis with evidence
• Priority-ordered improvement roadmap

---

Rationalizations (Do Not Skip)

| Rationalization | Why It's Wrong | Required Action | |-----------------|----------------|-----------------| | "Found some findings, assessment complete" | Assessment requires evaluating ALL 9 categories | Complete assessment of all 9 categories with evidence for each | | "I see events, auditing category looks good" | Events alone don't equal auditing maturity | Check logging comprehensiveness, testing, incident response processes | | "Code looks simple, complexity is low" | Visual simplicity masks composition complexity | Analyze cyclomatic complexity, dependency depth, state machine transitions | | "Not a DeFi protocol, MEV category doesn't apply" | MEV extends beyond DeFi (governance, NFTs, games) | Verify with transaction ordering analysis before declaring N/A | | "No assembly found, low-level category is N/A" | Low-level risks include external calls, delegatecall, inline assembly | Search for all low-level patterns before skipping category | | "This is taking too long" | Thorough assessment requires time per category | Complete all 9 categories, ask clarifying questions abou