doc-freshness

name	doc-freshness
description	Detects new features and changes across MegaETH repos that are not yet documented. Use when checking for documentation gaps, auditing doc coverage after a release, looking for undocumented changes, running a periodic doc sweep, or preparing release notes.

Documentation Freshness & Coverage Check

Check for undocumented changes across MegaETH repositories: $ARGUMENTS

Parse the arguments to determine the time window. Accepted inputs:

• A duration (e.g., 7d, 14d, 30d) — check merged PRs in that window.
• A date (e.g., 2025-03-01) — check merged PRs since that date.
• A git ref or tag (e.g., v0.5.0, rex3-release) — check merged PRs since that ref.
• A repo filter (e.g., a single repo name, or a space-separated list) — restrict to specific repos.

Default (no arguments): last 14 days, all in-scope repos discovered from session context (see below).

Scope

The caller provides the set of repos to scan by making them accessible to the Claude Code session — through the session's working directory and any additional paths granted via the Claude Code CLI flag --add-dir (claude --add-dir /path/to/repo …, repeatable). The skill itself does not receive these paths as arguments; it discovers them from the filesystem at runtime, rather than hardcoding repo names:

1. Treat every directory that contains a .git entry (within the working directory and every additional path granted to the session) as a candidate repo.
2. For each candidate, derive the GitHub slug from git remote get-url origin.
3. Classify each candidate by role using the table below, based on its README, top-level file layout, and recent PR titles. A repo may fit more than one role. If none of the roles clearly applies, classify it as unknown and still include it in the scan — but do not apply any role-specific gating (Phase 1.5) to it.
4. If the caller passed an explicit repo filter in $ARGUMENTS, restrict to matching names only.

If no repos are accessible beyond the documentation repo itself, ask the caller to re-run with the relevant source repos added.

Roles and doc-worthy change patterns

Role	What doc-worthy changes look like
EVM / protocol spec	New spec, gas constant changes, new or modified system contracts, opcode behavior changes, new resource limits
Execution client	New RPC methods, changed RPC behavior, new config flags, block execution changes, new node features
Public RPC gateway	New routes, changed caching or routing behavior, new error codes, rate-limit changes, WebSocket changes. Note: a public-endpoint gateway only reflects what MegaETH itself exposes — managed RPC providers (e.g., Alchemy) have their own configurations. Distinguish "unavailable on public endpoint" from "unsupported by MegaETH entirely."
Network infra config	Network parameter changes (chain IDs, RPC URLs, explorer URLs), new network deployments, config changes
L1 / bridge contracts	Bridge contract changes, L1/L2 interface changes, system config changes, new dispute game types
Sequencer / L2 coordinator	Sequencer behavior changes, payload building changes, L1 settlement changes
Token registry	New tokens added, token address changes, bridge-mechanic or OFT configuration changes
Release packaging	Release notes and hardfork schedules — determines which execution-client changes are released (via merged chore: release vX.Y.Z PRs) and which spec hardforks are active (via genesis config timestamps). Not scanned for code changes.

Workflow

Phase 1: Collect Recent Changes

For each in-scope repo (discovered per the Scope section), collect merged PRs in the time window.

gh pr list --repo {org}/{repo} --state merged --search "merged:>={since_date}" --json number,title,url,mergedAt,labels,body --limit 100

Derive {org}/{repo} from each repo's git remote get-url origin. If gh is not available or the repo is not accessible, fall back to local git log:

git log --oneline --since="{since_date}" --merges -- .

For each PR, record:

• PR number and title
• Merge date
• Labels (if any)
• A one-line summary of what changed (from PR title or body)

Phase 1.5: Determine Release Status

If the in-scope set includes an execution-client repo and a release-packaging repo (per the role table), apply the gating rules below. If either is absent, skip this phase and treat changes as continuously deployed.

Part A: Latest Released Execution-Client Version

Check the execution-client repo's GitHub Releases for the latest version and release date:

gh release list --repo {execution-client-slug} --limit 5

Cross-reference with the release-packaging repo to confirm the release has been announced to external partners:

gh pr list --repo {release-packaging-slug} --state merged --search "release {version} in:title" --json number,title,mergedAt --limit 1

If an execution-client release exists but has no corresponding release-packaging PR, note it as "Released but not yet announced — pending release note." Only execution-client changes included in a version that has been both released and announced should be considered doc-worthy. PRs merged after the latest announced release should be excluded and noted as "Unreleased — pending next release."

As a fallback, release-packaging version files typically follow a versions/{date}-v{version}.m4 naming pattern and can be listed via:

gh api repos/{release-packaging-slug}/contents/versions --jq '.[].name' | sort | tail -5

Part B: Hardfork Activation Gating

Some spec changes are tied to a named hardfork and should only be made public in documentation after the hardfork activates on mainnet.

1. Check release-packaging release notes for hardfork mentions:

   gh pr list --repo {release-packaging-slug} --state merged --search "hardfork in:body" --json number,title,body,mergedAt --limit 5
   

2. Extract the hardfork name and mainnet activation timestamp from the release note body.

3. Compare activation timestamp against current time:

   • If activated (timestamp in the past): spec changes for this hardfork are doc-worthy and can be made public.
   • If not yet activated (timestamp in the future): note as "Hardfork {name} not yet active — activates {date}. Defer public documentation."

Gating summary

• Execution client: gated by its GitHub Releases plus a release-packaging announcement.
• EVM / protocol spec: spec changes tied to a named hardfork are gated by activation time; tooling changes (like CLI flags) are doc-worthy regardless of hardfork status.
• Public RPC gateway, token registry, network infra: deployed continuously, not gated.

---

Phase 2: Triage — Doc-Worthy vs Internal

Classify each PR as doc-worthy or internal-only. A change is doc-worthy if it affects any of these surfaces:

Always doc-worthy (auto-include):

• New or modified RPC method (parameters, return values, error codes)
• Gas constant or limit changes
• New or modified system contract (address, interface, behavior)
• New spec or hardfork introduction
• Network parameter changes (chain ID, RPC URL, block time, explorer URL)
• New user-facing feature or behavior change
• Bridge or L1/L2 interface changes
• Breaking changes to any external API

Usually doc-worthy (include if impact is significant):

• New config flags that operators or integrators need to know about
• Performance characteristics that affect developer decisions
• New error codes or changed error behavior
• Deprecations

Internal-only (exclude):

• Pure refactoring with no behavioral change
• Test-only changes
• CI/CD pipeline changes
• Internal code reorganization
• Dependency bumps (unless they change behavior)
• Build system changes

When uncertain, include the PR in the report as "Possibly doc-worthy" with a note on why it's ambiguous.

Phase 3: Coverage Search

For each doc-worthy change, search the documentation for existing coverage.

1. Read docs/SUMMARY.md to understand the page inventory.
2. Search for the feature/method/constant name across docs/ using grep.
3. Check the most likely target page(s) based on the change type:

Change type	Check these pages first
Gas constant/limit	docs/spec/evm/dual-gas-model.md, docs/spec/evm/resource-limits.md, docs/dev/gas-model.md
New system contract	docs/spec/system-contracts/, docs/dev/system-contracts.md
RPC method	docs/dev/rpc/, docs/integration/rpc-providers.md
Network params	docs/integration/connect.md, docs/user/mainnet.md, docs/user/testnet.md
Spec/upgrade	docs/spec/upgrades/, docs/spec/hardfork-spec.md
Bridge/L1	docs/integration/bridges.md, docs/dev/architecture.md
Wallet-facing	docs/integration/wallets.md, docs/user/

4. Classify coverage:
   • Covered: The change is already documented accurately.
   • Partially covered: The feature is mentioned but the specific change is not reflected (e.g., old values, missing new parameters).
   • Not covered: No mention found in any documentation page.
   • Wrong layer: The change is documented but in the wrong layer (e.g., spec-level detail in user docs).

Phase 4: Prioritize Gaps

Assign priority to each gap:

Priority	Criteria
P0	Breaking change, incorrect values live in docs, security-relevant, or user-facing feature with no docs
P1	New feature or behavior change that developers/integrators need to know about
P2	Minor parameter change, non-breaking addition, or enhancement to existing feature

Phase 5: Report

Produce the report in the output format below.

Output Format

# Documentation Freshness Report

**Time window**: {since} to {now}
**Date**: {date}
**Repos scanned**: {list}
**PRs reviewed**: {total count}
**Doc-worthy changes**: {count}
**Coverage gaps found**: {count}

## Summary

| Repo        | PRs | Doc-worthy | Covered | Gaps |
| ----------- | --- | ---------- | ------- | ---- |
| {repo slug} | N   | N          | N       | N    |
| ...         | ... | ...        | ...     | ...  |

## Gaps (ordered by priority)

### F-001: {short description}

- **Priority**: P0 | P1 | P2
- **Source**: {repo} PR #{number} — {title} ({url})
- **Merged**: {date}
- **What changed**: {description of the change}
- **Coverage**: Not covered | Partially covered | Wrong layer
- **Target layer**: {User | Dev | Integration | Spec}
- **Target page**: {suggested page path — existing page to update, or new page to create}
- **What "done" looks like**: {acceptance criteria — what the doc update should contain}

### F-002: ...

## Covered Changes (no action needed)

<details>
<summary>N changes already documented (click to expand)</summary>

| #   | Repo   | PR        | Change    | Documented in     |
| --- | ------ | --------- | --------- | ----------------- |
| 1   | {repo} | #{number} | {summary} | `{doc page path}` |
| 2   | ...    | ...       | ...       | ...               |

</details>

## Internal-Only Changes (excluded)

<details>
<summary>N internal changes excluded (click to expand)</summary>

| #   | Repo   | PR                  | Why excluded                            |
| --- | ------ | ------------------- | --------------------------------------- |
| 1   | {repo} | #{number} — {title} | {reason: refactor, test-only, CI, etc.} |
| 2   | ...    | ...                 | ...                                     |

</details>

## Handoff

Impacted claim families for `/doc-correctness` verification:

- {family}: {list of specific claims to re-verify}

Impacted pages for `/doc-readability` review:

- {page path}: {reason — new content added, section rewritten, etc.}

Rules

• Always check PR titles AND bodies when triaging. Some PRs have uninformative titles but detailed bodies.
• When a PR touches both doc-worthy and internal code, classify based on the doc-worthy parts.
• If a repo is not accessible via gh, note it in the report and skip that repo. Do not fail the entire report.
• Do NOT create or edit documentation pages yourself. This skill produces a gap report, not content.
• When suggesting target pages, prefer updating existing pages over creating new ones. Only suggest a new page when no existing page is a natural fit.
• Include the PR URL for every finding so the user can quickly review the actual change.
• If the time window returns more than 100 PRs for a single repo, note this and suggest narrowing the window.

Related Skills

• After identifying gaps, run /doc-correctness on the impacted claim families to verify existing content is still accurate.
• After doc updates are made, run /doc-readability on the updated pages to ensure layer-appropriate tone.