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!
1---2name: code-maturity-assessor3description: 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.4---5
6# Code Maturity Assessor
7
8## Purpose
9
10Systematically assesses codebase maturity using Trail of Bits' 9-category framework. Provides evidence-based ratings and actionable recommendations.
11
12**Framework**: Building Secure Contracts - Code Maturity Evaluation v0.1.0
13
14---
15
16## How This Works
17
18### Phase 1: Discovery
19Explores the codebase to understand:
20- Project structure and platform
21- Contract/module files
22- Test coverage
23- Documentation availability
24
25### Phase 2: Analysis
26For each of 9 categories, I'll:
27- **Search the code** for relevant patterns
28- **Read key files** to assess implementation
29- **Present findings** with file references
30- **Ask clarifying questions** about processes I can't see in code
31- **Determine rating** based on criteria
32
33### Phase 3: Report
34Generates:
35- Executive summary
36- Maturity scorecard (ratings for all 9 categories)
37- Detailed analysis with evidence
38- Priority-ordered improvement roadmap
39
40---
41
42## Rating System
43
44- **Missing (0)**: Not present/not implemented
45- **Weak (1)**: Several significant improvements needed
46- **Moderate (2)**: Adequate, can be improved
47- **Satisfactory (3)**: Above average, minor improvements
48- **Strong (4)**: Exceptional, only small improvements possible
49
50**Rating Logic**:
51- ANY "Weak" criteria → **Weak**
52- NO "Weak" + SOME "Moderate" unmet → **Moderate**
53- ALL "Moderate" + SOME "Satisfactory" met → **Satisfactory**
54- ALL "Satisfactory" + exceptional practices → **Strong**
55
56---
57
58## The 9 Categories
59
60I 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).
61
62### Quick Reference:
63
64**1. ARITHMETIC**
65- Overflow protection mechanisms
66- Precision handling and rounding
67- Formula specifications
68- Edge case testing
69
70**2. AUDITING**
71- Event definitions and coverage
72- Monitoring infrastructure
73- Incident response planning
74
75**3. AUTHENTICATION / ACCESS CONTROLS**
76- Privilege management
77- Role separation
78- Access control testing
79- Key compromise scenarios
80
81**4. COMPLEXITY MANAGEMENT**
82- Function scope and clarity
83- Cyclomatic complexity
84- Inheritance hierarchies
85- Code duplication
86
87**5. DECENTRALIZATION**
88- Centralization risks
89- Upgrade control mechanisms
90- User opt-out paths
91- Timelock/multisig patterns
92
93**6. DOCUMENTATION**
94- Specifications and architecture
95- Inline code documentation
96- User stories
97- Domain glossaries
98
99**7. TRANSACTION ORDERING RISKS**
100- MEV vulnerabilities
101- Front-running protections
102- Slippage controls
103- Oracle security
104
105**8. LOW-LEVEL MANIPULATION**
106- Assembly usage
107- Unsafe code sections
108- Low-level calls
109- Justification and testing
110
111**9. TESTING & VERIFICATION**
112- Test coverage
113- Fuzzing and formal verification
114- CI/CD integration
115- Test quality
116
117For 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).
118
119---
120
121## Example Output
122
123When the assessment is complete, you'll receive a comprehensive maturity report including:
124
125- **Executive Summary**: Overall score, top 3 strengths, top 3 gaps, priority recommendations
126- **Maturity Scorecard**: Table with all 9 categories rated with scores and notes
127- **Detailed Analysis**: Category-by-category breakdown with evidence (file:line references)
128- **Improvement Roadmap**: Priority-ordered recommendations (CRITICAL/HIGH/MEDIUM) with effort estimates
129
130For a complete example assessment report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md).
131
132---
133
134## Assessment Process
135
136When invoked, I will:
137
1381. **Explore codebase**
139 - Find contract/module files
140 - Identify test files
141 - Locate documentation
142
1432. **Analyze each category**
144 - Search for relevant code patterns
145 - Read key implementations
146 - Assess against criteria
147 - Collect evidence
148
1493. **Interactive assessment**
150 - Present my findings with file references
151 - Ask about processes I can't see in code
152 - Discuss borderline cases
153 - Determine ratings together
154
1554. **Generate report**
156 - Executive summary
157 - Maturity scorecard table
158 - Detailed category analysis with evidence
159 - Priority-ordered improvement roadmap
160
161---
162
163## Rationalizations (Do Not Skip)
164
165| Rationalization | Why It's Wrong | Required Action |
166|-----------------|----------------|-----------------|
167| "Found some findings, assessment complete" | Assessment requires evaluating ALL 9 categories | Complete assessment of all 9 categories with evidence for each |
168| "I see events, auditing category looks good" | Events alone don't equal auditing maturity | Check logging comprehensiveness, testing, incident response processes |
169| "Code looks simple, complexity is low" | Visual simplicity masks composition complexity | Analyze cyclomatic complexity, dependency depth, state machine transitions |
170| "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 |
171| "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 |
172| "This is taking too long" | Thorough assessment requires time per category | Complete all 9 categories, ask clarifying questions about off-chain processes |
173| "I can rate this without evidence" | Ratings without file:line references = unsubstantiated claims | Collect concrete code evidence for every category assessment |
174| "User will know what to improve" | Vague guidance = no action | Provide priority-ordered roadmap with specific improvements and effort estimates |
175
176---
177
178## Report Format
179
180For detailed report structure and templates, see [REPORT_FORMAT.md](resources/REPORT_FORMAT.md).
181
182### Structure:
183
1841. **Executive Summary**
185 - Project name and platform
186 - Overall maturity (average rating)
187 - Top 3 strengths
188 - Top 3 critical gaps
189 - Priority recommendations
190
1912. **Maturity Scorecard**
192 - Table with all 9 categories
193 - Ratings and scores
194 - Key findings notes
195
1963. **Detailed Analysis**
197 - Per-category breakdown
198 - Evidence with file:line references
199 - Gaps and improvement actions
200
2014. **Improvement Roadmap**
202 - CRITICAL (immediate)
203 - HIGH (1-2 months)
204 - MEDIUM (2-4 months)
205 - Effort estimates and impact
206
207---
208
209## Ready to Begin
210
211**Estimated Time**: 30-40 minutes
212
213**I'll need**:
214- Access to full codebase
215- Your knowledge of processes (monitoring, incident response, team practices)
216- Context about the project (DeFi, NFT, infrastructure, etc.)
217
218Let's assess this codebase!
gabrielmoreira