Repository navigation
Description
Documentation Audit Report
Automated audit of docs/ and agent instruction files against source code and writing conventions.
Summary
| Dimension | Findings |
|---|---|
| Freshness | 0 gaps |
| Correctness | 2 issues |
| Readability | 1 issues |
Freshness
Time window: 2026-11-02 to 2026-11-16 (14 days)
PRs reviewed: 1 | Doc-worthy: 0 | Gaps: 0
Only #416 (#416, relax exact alloy pins) merged in the window; it is a dependency change and internal-only.
Correctness
Scope: spec ladder, system contract addresses, skill code paths, source layout, test layout, mega-evme src/ structure, SUMMARY.md page inventory, and all agent files.
Note: docs/AGENTS.md does not exist (the docs conventions live in docs/spec/AGENTS.md); the audit scope list should drop it.
The AGENTS.md spec ladder (EQUIVALENCE … REX6) matches MegaSpecId in crates/mega-evm/src/evm/spec.rs:41-64.
The test directory list and every code path in the skill mapping tables resolve against the tree.
Both findings below are carried over unchanged from the previous audit (#322, 2026-10-26).
C-001: bin/mega-evme/AGENTS.md STRUCTURE omits lib.rs; main.rs description stale
- Severity: Minor | Disposition: Stale
- Page:
bin/mega-evme/AGENTS.md, STRUCTURE - Doc says: "
src/main.rs: CLI bootstrap and panic hook." (nolib.rsentry; WHERE TO LOOK already refers tosrc/lib.rs) - Source says:
bin/mega-evme/src/lib.rsholds the module declarations and executable logic;bin/mega-evme/src/main.rs(81 lines) is intentionally minimal and only parses args, installs the panic hook and dispatches. - Suggested correction: Add
src/lib.rs: library crate with module declarations and command logic; changesrc/main.rsto "thin CLI entry point — parses args, installs the panic hook, dispatches intolib.rs."
C-002: Skill code-to-doc mapping tables omit pages/modules
- Severity: Minor | Disposition: Stale
- Pages:
.claude/skills/doc-freshness/SKILL.md,.claude/skills/doc-impact-check/SKILL.md - Doc says: No rows mapping to
docs/spec/evm/compute-gas.md,docs/spec/evm/selfdestruct.md, ordocs/mega-evme/commands/cache.md. - Source says: These pages exist and are in the SUMMARY files;
crates/mega-evm/src/limit/compute_gas.rsandbin/mega-evme/src/cache/exist. - Suggested correction: Add rows:
limit/compute_gas.rs→evm/compute-gas.md; SELFDESTRUCT code inevm/instructions.rs→evm/selfdestruct.md;bin/mega-evme/src/cache/→docs/mega-evme/commands/cache.md;bin/mega-evme/src/common/→ alsoconfiguration/state-management.md.
Readability
Scope: all pages in both SUMMARY.md files (automated pattern scan; no orphan pages, no style="success" hints, no Rex7 references).
R-001: Multiple sentences on one line (Minor)
- Rule: Structural Lint — one sentence per line
- Evidence (non-exhaustive, outside tables):
docs/spec/upgrades/rex6.mdlines 67, 68, 75docs/spec/upgrades/rex5.md(many lines, e.g. around 427–443, 557–590)docs/spec/evm/dual-gas-model.mdlines 16, 18docs/spec/evm/resource-limits.md,resource-accounting.md,gas-detention.md,selfdestruct.md,contract-limits.mddocs/spec/hardfork-spec.md,docs/spec/overview.md,docs/spec/upgrades/rex1.md,docs/spec/system-contracts/sequencer-registry.mddocs/mega-evme/commands/{run,tx,replay,cache}.md,docs/mega-evme/configuration/state-management.md
- Suggested fix: Split each sentence onto its own line (outside tables), then run
npx prettier --write 'docs/**/*.md'.
Activity
[-]Documentation audit — 2026-06-22[/-][+]Documentation audit — 2026-06-29[/+]mega-putin commentedon Jun 30, 2026
Understanding: This issue is asking for a small documentation sync so the agent guidance matches the current code layout. The concrete updates are to document the
mega-evmeCLI split betweenlib.rsandmain.rs, and to refresh the top-level test organization note ifcrates/mega-evm/tests/mutation/is present on the target branch.Approach:
bin/mega-evme/AGENTS.mdSTRUCTUREto addsrc/lib.rsand rewrite thesrc/main.rsentry to reflect the current split.bin/mega-evme/src/lib.rsandbin/mega-evme/src/main.rsas the source of truth for the wording, sincelib.rsnow owns the executable logic and panic hook whilemain.rsis only the thin CLI entry point.CLAUDE.mdTest Organizationto includemutation/with a short description, but only after verifying the directory exists in the branch being edited so the doc reflects the actual tree.crates/mega-evm/tests/mutation/is not present, so that part of the issue appears to depend on a newermainstate than this workspace currently has.main, the implementation should re-verify against the target branch before changingCLAUDE.md, otherwise we risk documenting a directory that is not actually in the tree.CLAUDE.mdshould describe the full test directory inventory or only the spec-oriented subsets.Reply
@mega-putin goto start implementation.[-]Documentation audit — 2026-06-29[/-][+]Documentation audit — 2026-10-26[/+][-]Documentation audit — 2026-10-26[/-][+]Documentation audit — 2026-11-16[/+]