Docs Analysis

Documentation Reconnaissance Methodology

Purpose

Rapidly understand what the protocol should do through documentation analysis. This is reconnaissance, not code analysis.

1. Documentation Discovery

Search Patterns

Glob("**/README*")
Glob("**/*.md")
Glob("**/docs/**/*")
Glob("**/SECURITY*")
Glob("**/*.pdf")

Priority Order

Skip These

• Code files (.sol, .rs, etc.)
• Test documentation
• CI/CD configuration

2. The 4 Essential Questions

Question 1: Where Is the Money?

Extract: Which contracts hold assets, TVL mentions, treasury.

Question 2: Who Can Move the Money?

User Paths:

Privileged Paths:

Extract: Function names, who can call, conditions.

Question 3: What Invariants Must Hold?

Explicit Invariants - Keywords:

• "must", "always", "never", "guaranteed", "ensures"
• Mathematical relationships: x + y = z, a <= b * c
• NatSpec: @invariant, @notice

Implicit Invariants - By Protocol Type:

Mark inferred invariants with [INFERRED].

Question 4: What Trust Assumptions Exist?

Extract: Who is trusted, for what, with what safeguards.

3. Protocol Type Classification

4. Extraction Process

Step 1: High-Level Understanding

Read overview documents to understand:

• Protocol purpose and value proposition
• Target users and use cases
• Integration with other protocols
• Economic model

Step 2: Mechanism Analysis

For each mechanism described:

1. Identify inputs and outputs
2. Note preconditions and postconditions
3. Extract mathematical relationships
4. Identify external dependencies

Step 3: Security Information

Look for:

• Security considerations sections
• Known limitations and risks
• Threat model descriptions
• Emergency procedures

Step 4: Gap Identification

Note what's MISSING:

• Undefined edge cases
• Unclear trust assumptions
• Missing invariants
• Ambiguous specifications

5. Quality Assessment

6. Edge Cases

Minimal Documentation

1. Note quality as "Poor" or "Minimal"
2. Flag ALL missing critical information
3. Infer what possible, mark as [INFERRED]
4. Recommend documentation improvements
5. Note increased audit risk

Conflicting Information

1. Note the conflict explicitly
2. List all versions found
3. Flag for clarification
4. Do not assume which is correct

Non-English Documentation

1. Note the language limitation
2. Extract what is possible
3. Flag for native speaker review

Output

Write findings to .vigilo/recon/docs-findings.md following the format in template.md.

Additional Resources

• template.md - Output template for documentation reconnaissance findings
• examples/minimal-output.md - Minimal output example for sparse documentation