# Readme Writer > Guidelines for writing module READMEs that explain how a module works to developers who need to use it or understand its internals. Use when documenting a module, package, or subsystem. Use when this capability is needed. - Skill: `tomevault-io/readme-writer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/readme-writer` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/readme-writer/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/readme-writer --- # Module README Writing Guide ## File Placement Place the README in the same folder as the module it explains, not at the package root. ``` # Good: README next to the module it documents sequencer-client/src/sequencer/README.md archiver/src/archiver/l1/README.md # Also good: Package-level README for small packages slasher/README.md ``` Use package-level READMEs when the package is small or you want to explain the package as a whole. ## Structure ### 1. Overview Start with 2-4 sentences explaining what the module does and where it fits in the system. ```markdown # L1 Transaction Utils This module handles sending L1 txs, including simulating txs, choosing gas prices, estimating gas limits, monitoring sent txs, speeding them up, and cancelling them. Each instance of `L1TxUtils` is stateful, corresponds to a given publisher EOA, and tracks its in-flight txs. ``` ### 2. Usage Context Explain when and how this module is used. Who calls it? Under what conditions? ```markdown ## Usage The slasher is integrated into the Aztec node and activates when: 1. The node is configured as a validator 2. The validator is selected as proposer for a slot 3. Slashable offenses have been detected ``` ### 3. Code Examples For utility-like modules, include a code snippet showing typical usage: ```typescript const versionManager = new version.VersionManager(DB_VERSION, rollupAddress, { dataDir: '/path/to/data', serviceName: 'my-database', }); await versionManager.checkVersionAndHandle( async () => await initializeFreshDatabase(), async (oldVersion, newVersion) => await migrate(oldVersion, newVersion), ); ``` ### 4. Core Concepts Define domain-specific terms and objects (blocks, checkpoints, slots, proposals, offenses, etc.). Explain relationships between them. ```markdown ### Slot vs Block vs Checkpoint - **Slot**: A fixed time window (e.g., 72 seconds) during which a proposer can build blocks - **Block**: A single batch of transactions, executed and validated - **Checkpoint**: The collection of all blocks built in a slot, attested by validators ``` ### 5. Main API List main methods without exhaustive parameter/return documentation. Focus on what each does: ```markdown ## API - `sendTransaction`: Sends an L1 tx and returns the tx hash. Consumes a nonce. - `monitorTransaction`: Monitors a sent tx and speeds up or cancels it. - `sendAndMonitorTransaction`: Combines sending and monitoring in a single call. ``` ### 6. State Lifecycle Use tables to document object states and transitions: ```markdown | From | To | Condition | Effect | |-|-|-|-| | `idle` | `sent` | `send_tx` | A new tx is sent and nonce is consumed | | `sent` | `speed-up` | `stall_time exceeded` | Tx replaced with higher gas | | `sent` | `mined` | `get_nonce(latest) > tx_nonce` | Tx confirmed | ``` ### 7. Timing and Sequence Use ASCII diagrams or tables for temporal flows: ```markdown T=0s Slot begins T=0-2s SYNCHRONIZING, PROPOSER_CHECK T=2s Start building Block 1 T=10s Block 1 deadline, start Block 2 ... T=72s Slot ends ``` For parallel operations, use multi-column timelines: ```markdown Time | Proposer | Validators -----|----------------------|------------------ 10s | Finish Block 1 | (idle) 12s | | Receive Block 1 18s | Finish Block 2 | Re-executing Block 1 ``` ### 8. Dependencies Explain what other modules this connects to: ```markdown ## Integration Flow 1. **Offense Detection**: Watchers emit `WANT_TO_SLASH_EVENT` when they detect violations 2. **Offense Collection**: SlashOffensesCollector stores offenses in SlasherOffensesStore 3. **Action Execution**: SequencerPublisher executes actions on L1 ``` ### 9. Error Handling Dedicate a section to unhappy paths and how deviations are handled: ```markdown ## Handling Timing Variations ### Slow Initialization If initialization completes at 3s instead of 2s: - Block 1 has 1s less time (7s instead of 8s) - Sub-slot deadlines remain fixed - Still enough time to build, just with fewer transactions ``` ### 10. Configuration Document configuration options with their purpose and constraints: ```markdown ## Configuration | Parameter | Default | Purpose | |-----------|---------|---------| | `slotDuration` | 72s | Total time for checkpoint | | `blockDuration` | 8s | Duration of each sub-slot | ``` Include considerations for how values relate to each other: ```markdown The `slashingOffsetInRounds` needs to be strictly greater than the proof submission window to be able to slash for epoch prunes or data withholding. ``` ### 11. Security Include when the module has security implications: ```markdown ## Vetoing The slashing system includes a veto mechanism that allows designated vetoers to block slash payloads during the execution delay period. This provides a safety valve for incorrectly proposed slashes. ``` ## Writing Style ### Explain Rationale Don't just document what happens—explain why: ```markdown # Bad The last sub-slot is reserved for validator re-execution. # Good The last sub-slot is reserved for validator re-execution. Validators execute blocks sequentially with a ~2s propagation delay. For the last block, there's no next block to build while validators re-execute, so we must wait for them to finish before collecting attestations. ``` ### Avoid Subjective Qualifiers ```markdown # Bad This is a key aspect of the design with critical security implications. # Good This provides a safety valve for incorrectly proposed slashes. ``` ### Be Succinct ```markdown # Bad It is important to note that the configuration values must satisfy certain constraints which will be explained in detail in the following section. # Good These values must satisfy certain constraints (explained below). ``` ### Include Only Relevant Sections Not every module needs every section. Skip sections that don't apply: - Small utilities don't need architecture sections - Stateless modules don't need lifecycle tables - Internal modules don't need usage examples - Not everything has security implications Ask yourself: "Does this section help someone understand or use this module?" If not, skip it. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/aztecprotocol) — claim your Tome and manage your conversions.