Draft Eip Narrative

Draft EIP narrative fields

Reduced-scope companion to convert-eip. That skill converts a whole EIP from scratch and fetches commit history, PR review comments, and call transcripts. This one fills in three narrative fields on a file that already exists, sourced primarily from the EIP text itself.

Scope: laymanDescription, benefits, tradeoffs — plus reviewer when absent. Anything else (stakeholderImpacts, faq, northStarAlignment, description, status or presentation history) is out of scope; use convert-eip for those.

Sources

In order. Stop as soon as the fields are supported.

1. The raw EIP markdown — always.

   gh api '/repos/ethereum/EIPs/contents/EIPS/eip-{N}.md' --jq '.content' | base64 -d
   

   If this 404s (unmerged EIP), fetch from the PR head ref — the file's pendingPullRequest field has the PR number.

   Abstract, Motivation, and Rationale carry laymanDescription and most benefits. Security Considerations and Backwards Compatibility carry most tradeoffs.

2. The Eth Magicians thread at the file's existing discussionLink — only when the EIP text alone does not support a claim. Use the Discourse JSON API, never WebFetch:

   curl -s "https://ethereum-magicians.org/t/{SLUG}/{ID}.json" | jq '.post_stream.posts[] | {username, created_at, cooked}'
   

Do not fetch commit history, PR review comments, or call transcripts. Those resolve provenance and status questions that this scope does not raise. Do not write a {N}-context.md file — report the sourcing in chat instead.

Field rules

Inherited from convert-eip, mirrored by the public guide at /champions.

• laymanDescription — what changes and why it matters, in plain language, no acronyms. Aim under ~60 words. Not a restatement of the title.
• benefits — about three strings. Each is one concrete claim a skeptical reader could check. Aim under ~16 words each. Prefer three strong, distinct claims over six overlapping ones; merge anything that restates a neighbour.
• tradeoffs — same shape. Real costs, complexity, and risks. Never write "requires a hard fork" or any variant. Nearly every EIP does; it says nothing.

The governing rule: be as factual and true to the resources as possible. Do not speculate. Do not shoehorn. At this scope that has teeth in three places:

• If the EIP has no downside worth naming, "tradeoffs": null is the correct answer, not a padded list. Files already carrying an explicit null keep it unless the EIP text names a real cost.
• If fewer than three honest benefits exist, write fewer. Do not pad to reach three.
• If the EIP text is too thin to write any of the three without inventing, skip the EIP and say so. A skipped EIP is a better outcome than a plausible-sounding fabrication.

reviewer

Forkcast treats expert vs bot as a provenance signal, so AI-drafted prose must be marked.

• Key absent → set "reviewer": "bot".
• Key already "expert" (or "staff") → never downgrade it. Leave it alone.

The loop

One EIP at a time. Ascending EIP number is the easy default since the run spans sessions, but order does not matter.

1. Read src/data/eips/{id}.json and fetch the EIP markdown.
2. Draft the three fields.
3. Edit the file in place — insert keys next to their neighbours rather than rebuilding the object. The auto-sync scripts and the champions builder both depend on existing key order.
4. npm run compile-eips (schema check).
5. Report: the drafted values, where each claim came from, anything deliberately left out, and git diff for the file.
6. Stop. Wait for approval before starting the next EIP.

Verify before handing back that git diff touches only the three fields and (where absent) reviewer — no reordered keys, no reformatted lines.

Committing is the user's call, and nothing gets committed without being asked. The natural rhythm is one commit per batch of approved EIPs, not one per EIP.

Periodically, and at the end: npm run audit-eips -- --fork {FORK} to watch the issue count fall, then npm run build. Spot-check a finished EIP at /eips/{id}?tab=analysis.