rippled/SCOPE_OF_WORK.md

XRPLD Automated Documentation System — Scope of Work

1. Problem Statement

The XRP Ledger daemon (xrpld) is a ~275,000 line C++ codebase with 1,183 source files across the core library, protocol layer, and application server. It is the single implementation of the XRP Ledger protocol and processes billions of dollars in value.

Despite this criticality, the codebase has minimal inline documentation. Only 569 of 1,183 files contain any Doxygen-style doc comments, and most of those are sparse — a class-level sentence or two, rarely covering individual methods, parameters, or behavioral invariants.

The only formal documentation effort — an external specification by Common Prefix — has fundamental structural problems:

• Drift is the default state. The spec lives in a separate repository with no CI linkage to the codebase. Every commit to rippled that changes behavior silently invalidates the spec. Even one week of drift makes the spec unreliable.
• Separate repo, separate context. No contributor has both repos open. When a bug comes in, the developer reads the code, not the spec. A recent bug would have been caught if the code itself was documented.
• No code-level documentation. The spec describes system-level behavior (payment engine, DEX) but does not document individual functions, classes, parameters, or invariants. A developer working on a specific function gets no help.
• Vendor dependency. Ripple has a critical documentation dependency on a single external firm. If the contract ends, the spec orphans.
• Perverse incentive. The vendor profits from complexity and drift. Cleaner code and better inline docs reduce the need for external specification work.

2. Solution as Built

An automated, in-repo documentation system with five components, all living alongside the code with no external repos and no external vendor dependency:

1. Module skills — Per-module knowledge files in docs/skills/ that capture the "soul" of each subsystem (key files, patterns, pitfalls, invariants). These are the durable, human-maintained context that the automated agent and human contributors both consult.
2. doc-agent (Claude Agent SDK app) — A TypeScript tool at .github/scripts/doc-agent/ with three modes: document (write Doxygen comments), review (detect drift on a diff), and regen-skills (rebuild a skill file from current code).
3. Doc-review GitHub Action — Runs the review mode on every PR; posts inline comments and a sticky summary. Currently warning-only.
4. Coverage enforcement — CI-enforced documentation coverage thresholds that ratchet up over time, preventing regression.
5. Developer slash commands — Claude Code commands in .claude/commands/ for onboarding, architecture questions, doc review, and bug pattern detection.

Documentation accuracy is enforced by CI the same way code style and test coverage are enforced today.

3. Deliverables — Built

3.1 Documentation Standards

docs/DOCUMENTATION_STANDARDS.md — canonical format guide defining:

• Javadoc-style /** ... */ Doxygen comments (matches existing convention)
• Documentation levels: file, class, public method, free function, enum
• Required Doxygen tags: @param, @return, @note, @invariant
• Quality rules: document behavior and invariants, never paraphrase signatures, terse style (2–5 lines for classes, 1–3 for functions)

3.2 Doxygen Configuration Changes

docs/Doxyfile:

• EXTRACT_ALL = NO (was YES) — undocumented entities are flagged rather than silently extracted
• GENERATE_XML = YES (was NO) — required for coverxygen to parse and measure documentation coverage

3.3 Module Skills

Thirteen module-level skill files in docs/skills/, each one a self-contained guide to a subsystem's responsibilities, key types, control flow, conventions, and common pitfalls:

Skill	Covers
consensus.md	XRPL consensus algorithm + RCL adapters
cryptography.md	CSPRNG, secure erasure, key handling
ledger.md	ReadView/ApplyView, state tables, sandbox
nodestore.md	RocksDB/NuDB/Memory backends
peering.md	Overlay + peerfinder
protocol.md	STObject, SField, Serializer, TER, Keylets
rpc.md	RPC handler conventions
shamap.md	SHA-256 Merkle radix tree
sql.md	SOCI database wrapper, checkpointing
test.md	Beast unit test framework conventions
transactors.md	Full transactor template
websockets.md	WS subscriptions/streams
index.md	Top-level codebase map

These skills serve a dual purpose: they are reference docs for human contributors, and they are injected as system-prompt context by the doc-agent (mapping in src/config.ts).

install-skills.sh installs the same files as Claude Code skills under .claude/skills/<name>/SKILL.md, so any Claude Code session in the repo picks them up automatically.

3.4 doc-agent (Claude Agent SDK)

A TypeScript application at .github/scripts/doc-agent/, built on @anthropic-ai/claude-agent-sdk. Three modes:

Mode	Purpose
document	Add Doxygen comments to a file or directory. Reads sibling <file>.ai.md context, the module skill, and the source file; uses permissionMode: 'acceptEdits' to write directly.
review	Given a git range or PR number, detect doc drift. Emits doc-review-report.md (sticky comment) and doc-review-comments.json (inline comments).
regen-skills	Rebuild a module's skill file at docs/skills/<module>.md from the module's .ai.md files plus existing skill content.

Layout:

doc-agent/
├── package.json          # Node >= 20.12, @anthropic-ai/claude-agent-sdk
├── biome.json            # lint + format
├── install-skills.sh     # copies docs/skills/*.md → .claude/skills/*/SKILL.md
├── prompts/              # System prompts as markdown (editable without code changes)
│   ├── document-file.md
│   ├── review-diff.md
│   └── regen-skill.md
└── src/
    ├── index.ts          # CLI entry (document | review | regen-skills)
    ├── config.ts         # Paths, model, MODULE_SKILL_MAP
    ├── prompt-loader.ts  # Loads prompts + injects module skill
    ├── document.ts
    ├── review.ts
    ├── regen-skills.ts
    └── types.ts

Notable design decisions:

• Prompts as markdown, not strings. Operators tune prompts without touching TypeScript or redeploying.
• .ai.md sidecar input. When documenting a file, the agent reads a sibling <file>.ai.md (high-signal prose generated upstream by the athenah-ai pipeline) as the authoritative source of intent. These are gitignored (*.ai.md in .gitignore) and discarded once the initial pass is complete.
• Model selection via env. DOC_AGENT_MODEL env var; default claude-sonnet-4-6.
• Repo root override. XRPLD_ROOT env var allows running the agent against a different checkout (useful in CI and local testing).

3.5 Documentation Coverage Pipeline

File	Purpose
.github/doc-coverage-thresholds.json	Per-module thresholds + quarterly ratchet schedule
.github/scripts/doc-coverage-check.py	Parses coverxygen LCOV, checks thresholds, generates PR report
.github/workflows/doc-coverage.yml	CI workflow: builds Doxygen XML, runs coverxygen, posts coverage to PR
cmake/XrplDocs.cmake	docs CMake target wiring

Flow:

1. On every PR touching C++ files, the workflow builds Doxygen XML for both the PR branch and the base branch (using ghcr.io/xrplf/ci/tools-rippled-documentation).
2. Coverxygen generates LCOV-format coverage from the XML.
3. The check script compares coverage against per-module thresholds.
4. Ratchet mode (no_decrease) prevents any PR from reducing coverage.
5. New files added in a PR require ≥ 80% doc coverage.
6. Results are posted as a sticky PR comment with per-module breakdown.

3.6 Doc-Review GitHub Action

File	Purpose
.github/workflows/doc-review.yml	CI workflow: runs on PR, posts review

The workflow invokes the doc-agent review mode (Section 3.4) directly — there is no separate CI script. The same code path serves CI and local use, so prompt and logic changes are tested in one place.

Flow:

1. On every PR, the workflow runs npm run review -- "$BASE..$HEAD" in the doc-agent directory.
2. doc-agent enumerates C++ files changed in the range, extracts diff hunks plus existing doc comments, and asks Claude per file whether the docs are still accurate.
3. Outputs doc-review-report.md (sticky PR comment) and doc-review-comments.json (inline review comments via actions/github-script).
4. Runs in warning-only mode — does not block merge.

Local invocation uses the same command: npm run review develop..HEAD or npm run review -- --pr 1234.

Cost: only changed files and changed hunks within those files are processed. Estimated ~$0.05–0.15 per PR.

3.7 Claude Code Slash Commands

Four developer-facing commands in .claude/commands/:

Command	Purpose
doc-review	Review doc accuracy for files changed on current branch
explain-module	Explain a module's architecture, classes, control flow, entry points
how-does-x-work	Trace a feature through the codebase with file/line references
find-bug-patterns	Scan code for common xrpld bug patterns (unchecked TER, integer overflow, missing amendment gates, etc.)

3.8 Full Codebase Documentation

The initial documentation pass covers 1,183 C++ files organized into 21 module-level PRs (see Section 5). The doc-agent document mode produces each PR in parallel across modules; each file's output is then domain-expert reviewed before merge.

4. Resources Required

4.1 People

Role	Responsibility
Documentation lead	Runs doc-agent document per module, reviews output, submits PRs, iterates on prompts in prompts/
Domain reviewers (rotating)	Review doc PRs for semantic accuracy in their area of expertise
CI/infrastructure	Deploys workflows, monitors costs, tunes false-positive rate on doc-review action

4.2 Infrastructure & Tools

Resource	Purpose
Anthropic API access	Powers the doc-agent (document, review, regen-skills) and the doc-review GitHub Action
Claude Agent SDK	@anthropic-ai/claude-agent-sdk Node package
Node.js >= 20.12	Native --env-file support; runs the doc-agent
GitHub Actions minutes	Doc-coverage workflow (Doxygen XML build + coverxygen) and doc-review workflow
Coverxygen	Python package, open source (MIT)
Doxygen	Already configured — uses existing ghcr.io/xrplf/ci/tools-rippled-documentation container
GitHub Actions secret	ANTHROPIC_API_KEY — for doc-review workflow
athenah-ai pipeline output	Generates .ai.md sidecar context files consumed by doc-agent document; gitignored, removed post-pass

4.3 Access & Permissions

• Write access to the rippled repository (or a fork for initial PRs)
• Ability to add GitHub Actions secrets (ANTHROPIC_API_KEY)
• Ability to modify required status checks (when promoting doc-review from warning to required)

5. Execution Plan

Module passes run in parallel — the doc-agent operates per-module independently, so foundation, protocol, and application layers are generated concurrently rather than sequentially. Module groupings below reflect dependency layering for review purposes, not a serial schedule.

Phase 0: Infrastructure — Complete

Tooling shipped as the foundation PR:

• docs/DOCUMENTATION_STANDARDS.md
• docs/Doxyfile modifications
• docs/skills/ — 13 module skills + index
• .github/scripts/doc-agent/ — Agent SDK app (document / review / regen-skills)
• .github/scripts/doc-agent/install-skills.sh
• .github/doc-coverage-thresholds.json
• .github/scripts/doc-coverage-check.py
• .github/workflows/doc-coverage.yml
• cmake/XrplDocs.cmake
• .github/workflows/doc-review.yml — invokes doc-agent review mode directly
• .claude/commands/ — 4 developer slash commands

Exit criteria met: All workflows pass on a test PR. Coverage report renders correctly. Doc-review action posts comments without false positives on a sample PR.

Phase 1: Foundation Modules

Lowest-level modules — everything else depends on these:

PR	Module	~Files	~Lines
1	include/xrpl/basics/ + src/libxrpl/basics/	63	~15K
2	include/xrpl/crypto/ + src/libxrpl/crypto/	6	~1.5K
3	include/xrpl/json/ + src/libxrpl/json/	18	~4K
4	include/xrpl/beast/ + src/libxrpl/beast/	88	~20K

Process per PR:

1. Create branch docs/module-<name> from develop.
2. Run npm run document <path> from .github/scripts/doc-agent/. The agent reads each file's .ai.md sidecar, the matching module skill, and the file itself, then writes Doxygen comments per the standards.
3. Domain expert reviews for semantic accuracy.
4. Run Doxygen build to validate no doc errors.
5. Merge; ratchet that module's threshold up to actual coverage level.

Phase 2: Protocol & Transaction Engine

PR	Module	~Files
5	include/xrpl/protocol/ + src/libxrpl/protocol/	150
6	include/xrpl/ledger/ + src/libxrpl/ledger/	68
7	include/xrpl/conditions/ + src/libxrpl/conditions/	8
8	include/xrpl/tx/ (core framework: Transactor, ApplyContext)	15
9	Payment transactors	9
10	DEX/AMM transactors	25
11	Escrow transactors	7
12	Other transactors (NFT, token, vault, check, etc.)	60
13	Pathfinding + invariants	30

Phase 3: Server & Application Layer

PR	Module	~Files
14	include/xrpl/server/ + src/libxrpl/server/	35
15	include/xrpl/nodestore/ + src/libxrpl/nodestore/	30
16	SHAMap	25
17	Resource management	17
18	Overlay + peerfinder	56
19	Consensus	15
20	Application core (ledger, main, misc, rdb)	133
21	RPC handlers	131

Once Phases 1–3 are merged, the doc-review action is promoted from warning to a required check.

Phase 4: Tests & Polish

• Document test files (brief docs only — test name + what it validates)
• Remove .ai.md sidecar files (they were transitional input only)
• Retrospective: false-positive rate, API costs, contributor feedback

6. Coverage Threshold Ratchet

Coverage thresholds are enforced per-module via .github/doc-coverage-thresholds.json:

• no_decrease ratchet — no PR may reduce coverage on a module below its current level.
• New files require ≥ 80% doc coverage regardless of module threshold.
• Per-module floors are raised manually as each module's PR lands, pinning the achieved coverage as the new floor.

There is no calendar-based ratchet; thresholds advance with the work.

7. Risk Assessment

Risk	Likelihood	Impact	Mitigation
LLM generates plausible but wrong docs	Medium	High	Every doc PR requires human domain expert review. .ai.md sidecars (athenah-ai) ground the agent in source-derived intent rather than free generation.
Doc-review action false positives annoy contributors	Medium	Medium	Warning-only mode initially. Promote to required only when FP rate < 5%. Prompts live in markdown (prompts/) and can be tuned without a code release.
Coverage enforcement blocks unrelated PRs	Low	Medium	no_decrease ratchet only; per-module floors raised manually as modules land.
Reviewer bandwidth bottleneck	Medium	Medium	PRs scoped to single modules. Reviewers rotate.
API costs exceed budget	Low	Low	Only diff hunks processed. Monthly budget cap with alerting.
Doxygen XML build adds CI time	Low	Low	Runs in parallel with existing checks. Uses existing documentation container.
Doc comments add code noise	Low	Low	Terse style enforced by standards. 2–5 lines per class, 1–3 per function.
Skill files drift from code	Medium	Medium	doc-agent regen-skills <module> rebuilds a skill from current .ai.md files; intended to be run periodically.

8. Success Metrics

Metric	Measurement
Documentation coverage (public API)	Coverxygen LCOV reports in CI
Doc drift catch rate	Sample audit of merged PRs vs doc-review output
False positive rate (doc-review action)	Track dismissed vs accepted suggestions
Spec-vs-code contradictions	Bug reports citing wrong documentation
Contributor satisfaction	Periodic survey: "docs helped me understand the code"
Onboarding time	Measure across new contributors before/after
API cost	Anthropic API billing dashboard

9. What This Replaces

This system does not replace the Common Prefix formal verification work directly — formal verification and code documentation solve different problems. However, it eliminates the need for an external specification as the "source of truth" for how xrpld behaves:

Need	Before	After
"What does this function do?"	Read the code, guess	Read the inline Doxygen doc
"How does the payment engine work?"	Read Common Prefix spec (maybe stale)	Read docs/skills/transactors.md or run /explain-module
"Did this PR break any documented behavior?"	Manual review, hope someone notices	Doc-review action flags it automatically
"What's our documentation coverage?"	Unknown	Measured per-module in every PR
"Is the spec up to date?"	Check manually, probably not	Docs are in-repo, enforced by CI
"Where do I start in module X?"	Ask in chat	Read the module skill in docs/skills/

10. Out of Scope

• Formal verification. This project documents code behavior; it does not prove correctness. Formal verification is a separate discipline.
• External-facing API documentation. This covers the C++ source code, not the JSON-RPC API documentation on xrpl.org.
• Test coverage. Test file documentation is brief and optional. Test coverage measurement is handled by existing Codecov integration.
• Architectural decision records. Module-level READMEs already exist for key subsystems. This project adds function/class-level docs and the module skills layer, not system-level ADRs.