Doc Correctness

Documentation Correctness Verification

Verify factual claims in the documentation against implementation source: $ARGUMENTS

Parse the arguments to determine scope. Accepted inputs:

• A single page path (e.g., docs/spec/evm/dual-gas-model.md) — verify claims on that page.
• A directory (e.g., docs/spec/evm/) — verify all pages in that directory.
• A claim family (e.g., gas, system-contracts, upgrades, agent-files) — verify all claims of that type across all pages.
• all — verify every page listed in docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md, plus all agent files (AGENTS.md, CLAUDE.md, docs/spec/AGENTS.md, bin/mega-evme/AGENTS.md, REVIEW.md, .claude/skills/*/SKILL.md).

Default (no arguments): verify all pages.

Claim Families

Every verifiable claim in the docs falls into one of these families.

Agent File Verification

Agent instruction files (AGENTS.md, CLAUDE.md, docs/spec/AGENTS.md, bin/mega-evme/AGENTS.md, REVIEW.md, .claude/skills/*/SKILL.md) contain code-related claims that can go stale. Treat them as additional pages to audit. Key claims to verify:

• Spec progression list in AGENTS.md: Does it match the actual MegaSpecId enum in spec.rs?
• Unstable spec marker in AGENTS.md: Is the marked unstable spec still the latest?
• System Contracts table in AGENTS.md: Do the contracts, addresses, and purposes match the source?
• Core Source Layout in AGENTS.md: Do the listed modules and descriptions match the actual directory structure?
• Code-to-doc mapping tables in skill files: Are all doc pages and code paths still valid?
• Hardfork-to-spec mapping in AGENTS.md: Does it match hardfork.rs?
• Test organization in AGENTS.md: Does it match actual test directory structure?
• mega-evme STRUCTURE in bin/mega-evme/AGENTS.md: Do the listed modules match the actual bin/mega-evme/src/ directory layout?

Workflow

Phase 1: Claim Extraction

Read the target page(s) and extract every verifiable claim. A claim is any statement that can be checked against source code:

• Numeric values: gas costs, limits, caps, multipliers, addresses, bucket sizes.
• Behavioral rules: "X always/never happens", "Y reverts when Z", "A is charged before B".
• Interface definitions: function signatures, event signatures, error selectors, parameter names.
• Relationships: "Spec X introduced feature Y", "Contract Z is available since Rex2".
• Security claims: Attack vectors, invariants, and risk consequences stated in Security Considerations sections.

For each claim, record:

• The exact text from the doc.
• The page path and section.
• The claim family.

Phase 2: Source Resolution

For each claim, locate the authoritative source:

1. Match the claim family to the source locations in the table above.
2. Find the specific source: search for the constant name, function signature, address, or behavioral code path.
   • For constants: grep for the constant name or numeric value in crates/mega-evm/src/constants.rs and related files.
   • For interfaces: read the Solidity contract source in crates/system-contracts/contracts/.
   • For upgrade claims: check spec.rs and hardfork.rs for the spec gate.
   • For behavioral rules: trace the code path that implements the rule.

Budget: Do not spend more than ~5 targeted file reads per claim. If the source cannot be found after 5 reads, mark the claim as Ambiguous.

Phase 3: Verification

For each claim, compare the doc text against the source and assign a disposition:

Phase 4: Report

## Correctness

**Scope**: {what was verified}
**Claims checked**: {count}

### Summary

| Disposition | Count |
|-------------|-------|
| Verified | N |
| Incorrect | N |
| Stale | N |
| Ambiguous | N |
| Version-dependent | N |

### Findings (Incorrect / Stale / Ambiguous / Version-dependent only)

#### C-001: {short description}

- **Severity**: Blocker | Major | Minor
- **Disposition**: {disposition}
- **Claim family**: {family}
- **Page**: {path}
- **Section**: {heading}
- **Doc says**: "{exact text from doc}"
- **Source says**: "{what the source actually shows}"
- **Source location**: `{file}:{line}`
- **Suggested correction**: {concrete edit to the doc text}

#### C-002: ...

### Verified Claims

<details>
<summary>N claims verified</summary>

| # | Page | Claim | Source | Line |
|---|------|-------|--------|------|
| 1 | {path} | {claim summary} | `{file}` | {line} |

</details>

Severity definitions:

• Blocker: Incorrect numeric values (gas costs, limits, addresses), wrong spec attribution, wrong interface signature — would cause implementation bugs.
• Major: Stale values from a previous spec, missing version qualification, misleading behavioral description.
• Minor: Ambiguous claim that could be misread, minor wording imprecision that doesn't change meaning.

Rules

• Verify against actual source code, not against other documentation pages.
• If a claim references a specific spec (e.g., "Rex3 introduced X"), verify it was indeed that spec, not an earlier or later one.
• Do NOT fix the issues yourself unless the user explicitly asks. This skill produces a report, not edits.
• When verifying gas constants, check both the constant definition AND its usage context (per-transaction? per-opcode? per-block?).
• When verifying Security Considerations claims, confirm that the stated invariant is real — check that the code actually enforces it.
• Every numeric value MUST be verified against crates/mega-evm/src/constants.rs or the relevant source file. Do not trust other documentation pages as a source of truth.