# Doc Readability

> Evaluates documentation readability, structure, and compliance with docs/spec/AGENTS.md conventions. Use when reviewing doc quality, auditing formatting compliance, checking a page before publishing, or running a readability audit across the specification.

- Skill: `megaeth-labs/doc-readability` (Agent Skill)
- Install (CLI): `npx skillmds@latest add megaeth-labs/doc-readability`
- Raw SKILL.md: https://api.skillmd.com/api/skills/megaeth-labs/doc-readability/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: megaeth-labs (https://skillmd.com/u/megaeth-labs)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/megaeth-labs/doc-readability

---


# Documentation Readability Evaluation

Evaluate readability and spec-layer compliance for: $ARGUMENTS

Parse the arguments to determine scope.
Accepted inputs:

- A single page path (e.g., `docs/spec/evm/dual-gas-model.md`) — evaluate that page.
- A directory (e.g., `docs/spec/evm/`) — evaluate all pages in that directory.
- `all` — evaluate every page listed in `docs/spec/SUMMARY.md` and `docs/mega-evme/SUMMARY.md`.

Default (no arguments): evaluate all pages.

## Setup

Before evaluating any page:

1. Read `docs/spec/AGENTS.md` — the authoritative writing rules for this specification.
2. Read `docs/spec/SUMMARY.md` — the spec page inventory.
3. Read `docs/mega-evme/SUMMARY.md` — the mega-evme page inventory.

**Note**: Pages under `docs/mega-evme/` follow reference-doc conventions, not spec-page conventions.
They may omit frontmatter `spec` fields, Specification/Constants sections, and normative RFC 2119 language.
Apply Structural Lint, Cross-Linking, and Formatting checks as normal, but adapt Page Structure Compliance and Normative Language checks to reference-doc expectations.

## Evaluation Checklist

### 1. Structural Lint

- [ ] **Frontmatter**: YAML frontmatter present with a `spec` field (concept pages) or `description` field (upgrade pages).
- [ ] **Heading hierarchy**: Exactly one H1 (`#`). Sections use H2 (`##`), subsections H3 (`###`). No heading level skips.
- [ ] **One sentence per line**: Each sentence on its own line for diff readability. Flag paragraphs where multiple sentences share a line.
- [ ] **Page in SUMMARY.md**: The page appears in `docs/spec/SUMMARY.md`. Flag orphaned pages.

### 2. Page Structure Compliance

Concept pages MUST follow this section order (per `docs/spec/AGENTS.md`):

```
# Page Title
Abstract
## Motivation
## Specification
## Constants
## Rationale
## Security Considerations
## Spec History
```

- [ ] **Required sections present**: For pages defining behavioral rules, check that Specification and Constants sections exist.
- [ ] **Section order**: Sections appear in the prescribed order.
- [ ] **Upgrade page structure**: Upgrade pages under `upgrades/` follow the required structure (Summary, What Changed with Previous/New behavior, Developer Impact, Safety and Compatibility, References).

### 3. Normative Language

- [ ] **MUST/SHALL/SHOULD/MAY usage**: Behavioral rules in Specification sections use uppercase normative keywords per RFC 2119.
- [ ] **No normative keywords outside Specification/Security**: Motivation, Rationale, and Spec History use plain English only.
- [ ] **No implementation details**: Specification sections do not reference code patterns, function names, or implementation strategies.
- [ ] **No developer guidance**: No "tips", "best practices", "how to use", or "you should" language.
- [ ] **No user-facing language**: No second-person ("you") in Specification sections.

### 4. Constants and Formulas

- [ ] **Named constants**: Every numeric value in the Specification is defined as a named constant in the Constants table.
- [ ] **No magic numbers**: Formulas reference constant names, not embedded numeric values.
- [ ] **Constant rows complete**: Each constant row has name, value, and one-line description.

### 5. Spec Versioning

- [ ] **Latest spec implicit**: Main content does not mention the latest spec name in Specification, Constants, or Motivation sections.
- [ ] **Unstable content in `<details>`**: Content for the unstable spec (the one still open for change) is wrapped in `<details>` blocks. A frozen spec that no network has scheduled yet is NOT unstable — its content belongs in main prose, with its network status shown by the upgrade page's activation tabs.
- [ ] **Spec History format**: Overview pages use simple lists; concept pages may use tables. Only list specs that changed relevant behavior.

### 6. Cross-Linking

- [ ] **Glossary first-use linking**: First mention of MegaETH-specific terms links to glossary entry. No over-linking.
- [ ] **Spec names link to upgrade pages**: When a spec is mentioned by name, it links to `upgrades/{spec}.md`.
- [ ] **Anchor targets are headings**: Any `#fragment` link target is a markdown heading, not bold text.
- [ ] **No external user/dev links**: Spec pages do not link to external user docs or developer docs.

### 7. Formatting

- [ ] **Tables for structured data**: Gas costs, opcode lists, resource limits, constants use tables.
- [ ] **Unambiguous table values**: "Unlimited", "No limit", or "N/A" instead of bare dashes.
- [ ] **Hint blocks**: `{% hint style="info" %}` used sparingly for non-normative notes. No `{% hint style="success" %}`. `{% hint style="danger" %}` only for deprecation notices.

## Output Format

```markdown
## Readability

**Scope**: {what was evaluated}
**Pages evaluated**: {count}

### Summary

| Result | Count |
|--------|-------|
| Pass | N |
| Fail | N |
| Total findings | N |

### Per-Category Results

For each page, report pass/fail per checklist category.
Categories with no findings still appear as "Pass" — do not silently omit them.

| Category | Result | Findings |
|----------|--------|----------|
| Structural Lint | Pass / Fail | N |
| Page Structure Compliance | Pass / Fail | N |
| Normative Language | Pass / Fail | N |
| Constants and Formulas | Pass / Fail | N |
| Spec Versioning | Pass / Fail | N |
| Cross-Linking | Pass / Fail | N |
| Formatting | Pass / Fail | N |

### Findings

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

- **Severity**: Blocker | Major | Minor
- **Page**: {path}
- **Rule**: {which check failed}
- **Evidence**: {excerpt or description}
- **Suggested fix**: {concrete edit}

#### R-002: ...
```

**Severity definitions**:

- **Blocker**: Content violates core spec conventions — implementation details in Specification section, normative keywords in Rationale, spec linking to external user/dev docs.
- **Major**: Missing frontmatter, heading hierarchy violations, wrong hint block style, missing required sections.
- **Minor**: Multi-sentence lines, missing glossary links, suboptimal block usage, minor formatting drift.

## Rules

- Evaluate against the `docs/spec/AGENTS.md` rules as written. Do not invent additional style rules.
- When a page has zero findings, still count it as "Pass" in the summary.
- Sort findings by severity (Blocker first), then by page.
- Do NOT fix the issues yourself unless the user explicitly asks. This skill produces a report, not edits.
- If a finding is ambiguous (could be intentional), note it as Minor with "Review: may be intentional".