RTLDesignSherpa

Authoring a per-module reference page under docs/markdown (RTLCommon/RTLMath/RTLAmba) - the local .md style (header table, Overview, Architecture, Top-level Interface, Data model, Timing, Related, Test) and the SV header block that mirrors it. Use whenever you add or change an RTL block and need its docs/markdown page, and keep the book index in sync.

What kind of documentation lives where in this repo - handbook (method) vs docs/markdown (reader-facing) vs vault/Tasks (work) vs beside-code (CLAUDE.md, PRD). The rule that a beside-code README is a link, never a standalone guide, and that style guides / how-tos never live in the RTL tree. Use before creating, moving, or "tidying" any .md file, and when reviewing an area's meta-docs.

Coverage methodology - Verilator line/toggle coverage per component, functional coverage expectations, and the monbus packet-type coverage matrix. Use when adding tests, closing coverage, or preparing a board-gate sign-off.

The Sherpa documentation pipeline - md_to_docx with --style, LoF/LoT/LoW caption encoding, book indexes, RTL PDF generation, HAS/MAS vs operator guides. Use before generating or restructuring any deliverable doc.

Filelist rules - EVERY module MUST have a .f and MUST be registered in bin/filelists.toml. Components own their compile closure, consumers -f include, never hand-list another area's sources. Use when adding ANY new RTL module, test, or .f file.

Formal verification flow - SymbiYosys via sv2v flatten, in-RTL ifdef FORMAL properties, mutation-checking every new assertion, harness vacuity traps. Use when writing properties, regenerating proofs, or after changing any module with a formal dir.

HARD RTL design guidelines - reset macros, CDC, valid/ready contracts, streaming no-FSM pattern, SRAM rules, sizing invariants, signal-naming audit. Use when writing or reviewing any RTL.

Signal-contracts + K-map workbooks (xlsx) for a component - contract sheets per interface and computed Karnaugh maps for key combinational decisions. Use when documenting or reviewing decision logic in engines/schedulers/arbiters.

RDS-DV testbenches compose THREE ORTHOGONAL choices - BFM (who drives), sequence (what traffic), randomization (what timing). Pick each deliberately; using the right BFM says nothing about whether the test stresses anything. Points at the authoritative per-family RDS-DV docs. Use when starting or reviewing ANY testbench.

Use the RDS-DV framework BFMs (GAXI/AXI4/AXIL/APB/AXIS/MonBus) instead of hand-rolling drivers, monitors, or packet decoders. Covers the factory map, decision tree, and the known traps. The BFM is only ONE of three orthogonal axes - see also rds-dv-axes (sequences) and rds-dv-randomization (timing).

Delay/traffic randomization in RDS-DV - the 19 named FlexConfigGen profiles, which layer to use, and the rule that randomized traffic does NOT prove fairness or arbitration correctness. Use when shaping stimulus timing, writing an arbiter/scheduler/picker test, or choosing a delay profile.

How to run a regression correctly - always "make clean-all && make run-all-{gate,func,full}-parallel", never a bare pytest. Use whenever running or re-running any test suite in val/ or projects/components/, or before reporting a suite as passing.

External doc-review rounds (Kimi) - bundle building, serial dispatch, round protection, token budgets, findings triage (doc-fix vs RTL-fix), measuring integration status rather than trusting commit history, verifying fixes with clean rebuilds + mutation checks, and the humanization pass. Use when sending docs for critique, triaging findings, or running the humanizer.

Where project tasks/TODOs live and how to track them - the /vault/Tasks/<area>/ directory with open/active/closed/dropped lifecycle pages. Use whenever you would record a TODO, start/finish a task, or are tempted to create a TASKS.md or TODO.md next to code.

The UART characterization-harness methodology - one host program running identically against cocotb sim and the FPGA. Sim transport, regmap-by-name, board bring-up gotchas (JTAG serials, ttyUSB). Use for any board characterization flow.