Skip to content

Documentation audit — 2026-11-16 #322

Open

Description

@claude

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." (no lib.rs entry; WHERE TO LOOK already refers to src/lib.rs)
  • Source says: bin/mega-evme/src/lib.rs holds 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; change src/main.rs to "thin CLI entry point — parses args, installs the panic hook, dispatches into lib.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, or docs/mega-evme/commands/cache.md.
  • Source says: These pages exist and are in the SUMMARY files; crates/mega-evm/src/limit/compute_gas.rs and bin/mega-evme/src/cache/ exist.
  • Suggested correction: Add rows: limit/compute_gas.rs → evm/compute-gas.md; SELFDESTRUCT code in evm/instructions.rs → evm/selfdestruct.md; bin/mega-evme/src/cache/ → docs/mega-evme/commands/cache.md; bin/mega-evme/src/common/ → also configuration/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.md lines 67, 68, 75
    • docs/spec/upgrades/rex5.md (many lines, e.g. around 427–443, 557–590)
    • docs/spec/evm/dual-gas-model.md lines 16, 18
    • docs/spec/evm/resource-limits.md, resource-accounting.md, gas-detention.md, selfdestruct.md, contract-limits.md
    • docs/spec/hardfork-spec.md, docs/spec/overview.md, docs/spec/upgrades/rex1.md, docs/spec/system-contracts/sequencer-registry.md
    • docs/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

  1. added
    comp:docChanges in the documentation
    agentGenerated by AI agents
    on Jun 22, 2026
  2. changed the title [-]Documentation audit — 2026-06-22[/-] [+]Documentation audit — 2026-06-29[/+] on Jun 29, 2026
  3. mega-putin commented on Jun 30, 2026

    @mega-putin
    Contributor
    1. 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-evme CLI split between lib.rs and main.rs, and to refresh the top-level test organization note if crates/mega-evm/tests/mutation/ is present on the target branch.

    2. Approach:

    • Update bin/mega-evme/AGENTS.md STRUCTURE to add src/lib.rs and rewrite the src/main.rs entry to reflect the current split.
    • Use bin/mega-evme/src/lib.rs and bin/mega-evme/src/main.rs as the source of truth for the wording, since lib.rs now owns the executable logic and panic hook while main.rs is only the thin CLI entry point.
    • Update CLAUDE.md Test Organization to include mutation/ with a short description, but only after verifying the directory exists in the branch being edited so the doc reflects the actual tree.
    • Keep the edits minimal and consistent with repo markdown conventions, including one sentence per line if any prose needs to be reflowed.
    • Run a quick verification pass with file listings / grep to confirm the updated claims match the repository structure after editing.
    1. Risks:
    • In the current checkout I inspected, crates/mega-evm/tests/mutation/ is not present, so that part of the issue appears to depend on a newer main state than this workspace currently has.
    • If the local branch is behind main, the implementation should re-verify against the target branch before changing CLAUDE.md, otherwise we risk documenting a directory that is not actually in the tree.
    • The scope is documentation-only, so the main human judgment is whether CLAUDE.md should describe the full test directory inventory or only the spec-oriented subsets.

    Reply @mega-putin go to start implementation.

  4. changed the title [-]Documentation audit — 2026-06-29[/-] [+]Documentation audit — 2026-10-26[/+] on Oct 26, 2026
  5. changed the title [-]Documentation audit — 2026-10-26[/-] [+]Documentation audit — 2026-11-16[/+] on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

agentGenerated by AI agentscomp:docChanges in the documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions