code-maturity-assessor

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.

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.

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.

Assessment Process

When invoked, I will:

Explore codebase
- Find contract/module files
- Identify test files
- Locate documentation
Analyze each category
- Search for relevant code patterns
- Read key implementations
- Assess against criteria
- Collect evidence
Interactive assessment
- Present my findings with file references
- Ask about processes I can't see in code
- Discuss borderline cases
- Determine ratings together
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 about off-chain processes
"I can rate this without evidence"	Ratings without file:line references = unsubstantiated claims	Collect concrete code evidence for every category assessment
"User will know what to improve"	Vague guidance = no action	Provide priority-ordered roadmap with specific improvements and effort estimates

Report Format

For detailed report structure and templates, see REPORT_FORMAT.md.

Structure:

Executive Summary
- Project name and platform
- Overall maturity (average rating)
- Top 3 strengths
- Top 3 critical gaps
- Priority recommendations
Maturity Scorecard
- Table with all 9 categories
- Ratings and scores
- Key findings notes
Detailed Analysis
- Per-category breakdown
- Evidence with file:line references
- Gaps and improvement actions
Improvement Roadmap
- CRITICAL (immediate)
- HIGH (1-2 months)
- MEDIUM (2-4 months)
- Effort estimates and impact

Ready to Begin

Estimated Time: 30-40 minutes

I'll need:

Access to full codebase
Your knowledge of processes (monitoring, incident response, team practices)
Context about the project (DeFi, NFT, infrastructure, etc.)

Let's assess this codebase!