Purpose of these docs

allowed-tools: Read, Edit, Write, Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git branch *), Bash(git status *), Bash(ls *), Glob, Grep, LSP, Agent description: "Review all codebase documentation files under .claude/ and per-crate CLAUDE.md files, and fix any that have drifted from the actual code. This is a documentation-only task -- do not modify any source code." user-invocable: true

Review all codebase documentation files under .claude/ and per-crate CLAUDE.md files, and fix any that have drifted from the actual code. This is a documentation-only task -- do not modify any source code.

Purpose of these docs

These docs exist to help AI agents quickly understand the codebase so they can solve tasks. Every piece of information must serve that goal. Do NOT:

• Add exhaustive field-by-field listings unless a field is surprising or critical to understand
• Document obvious things (e.g. "mod.rs contains module declarations")
• Be pedantic about minor wording differences that don't affect understanding
• Add information that an agent could trivially find by reading the source file

DO focus on:

• What each module does and how it relates to other modules
• Key types, traits, and their roles -- names and purpose, not exhaustive field lists
• Data flow -- how information moves through the system
• Non-obvious behavior -- reorg handling, partial blocks, temporal versioning, DCI, etc.
• Correct interface signatures for core traits (ProtocolGateway, ContractStateGateway, AccountExtractor, TokenPreProcessor, TokenAnalyzer, EntryPointTracer, SwapQuoter, ProtocolSim) -- agents need these to implement or call them

What counts as a real discrepancy

Only fix things that would mislead an agent trying to work with the code:

• A module/file listed in docs that no longer exists, or a new module not listed
• A trait signature in docs that doesn't match the actual trait (wrong method names, wrong parameters, wrong return types)
• An endpoint path, method, or handler name that's wrong
• A struct or enum documented with fields/variants that don't exist (or missing ones that are important)
• A data flow step that's no longer accurate
• A feature flag that was added or removed

Do NOT "fix" things like:

• Minor differences in how a concept is described vs how it reads in code
• Adding more detail to something that's already clear enough

Documentation layout

This repo's documentation lives in two places:

1. .claude/ directory

2. Per-crate CLAUDE.md files

| protocols/CLAUDE.md | Index of sub-directories | | protocols/substreams/CLAUDE.md | WASM Substreams modules: layout, templates, release process | | protocols/testing/CLAUDE.md | Integration test runner: CLI, env vars | | protocols/adapter-integration/CLAUDE.md | Foundry VM adapter tests |

Process

This skill runs 3 agents in parallel, then applies changes based on their combined findings.

Agent 1: Code Reader (subagent_type: Explore)

Reads every doc file and compares it against the actual source code. This agent does NOT make edits -- it only reports discrepancies.

Prompt for Agent 1:

You are auditing documentation against the actual Rust source code in a Cargo workspace. Do NOT edit any files. Only report discrepancies.

Prefer LSP over Glob/Grep for code exploration. Use documentSymbol to list module contents, goToDefinition and findReferences for trait/type verification, workspaceSymbol for locating types across crates. Fall back to Glob/Grep/Read for docs, config files, and non-Rust files.

For each doc file below, read it, then read the corresponding source files and report any concrete discrepancy that would mislead an agent. Focus on: wrong/missing modules, wrong trait signatures, wrong struct fields/variants, wrong endpoint paths, wrong data flow, wrong feature flags.

Workspace entrypoint (.claude/CODEBASE.md):

• Compare "Workspace Module Map" against actual crates in Cargo.toml [workspace.members]
• Compare feature flags table against each crate's Cargo.toml [features]
• Compare "End-to-End Data Flow" diagram against crates/tycho-indexer/src/extractor/protocol_extractor.rs, crates/tycho-indexer/src/services/, and crates/tycho-client/src/feed/
• Compare CLI commands table against crates/tycho-indexer/src/cli/
• Compare env vars table against actual usage (search for env::var / std::env)
• Compare testing section against CI config (.github/workflows/)

tycho-indexer (crates/tycho-indexer/CLAUDE.md):

• Compare module map against crates/tycho-indexer/src/ directory tree
• Compare ProtocolExtractor description against crates/tycho-indexer/src/extractor/protocol_extractor.rs
• Compare RPC endpoints table against crates/tycho-indexer/src/services/rpc.rs
• Compare services/middleware listing against crates/tycho-indexer/src/services/middleware/
• Compare DCI description against crates/tycho-indexer/src/extractor/dynamic_contract_indexer/

tycho-common (crates/tycho-common/CLAUDE.md):

• Compare module organisation against crates/tycho-common/src/ directory tree
• Compare trait abstractions against crates/tycho-common/src/storage.rs and crates/tycho-common/src/traits.rs
• Compare simulation module against crates/tycho-common/src/simulation/
• Compare data flow diagram against actual inter-crate dependencies

tycho-storage (crates/tycho-storage/CLAUDE.md):

• Compare module map against crates/tycho-storage/src/postgres/ directory tree
• Compare write order against DBCacheWriteExecutor in crates/tycho-storage/src/postgres/cache.rs
• Compare gateway descriptions against crates/tycho-storage/src/postgres/cache.rs and direct.rs

tycho-ethereum (crates/tycho-ethereum/CLAUDE.md):

• Compare module map against crates/tycho-ethereum/src/ directory tree
• Compare trait implementations table against actual impl blocks
• Compare entrypoint_tracer contents against crates/tycho-ethereum/src/services/entrypoint_tracer/

tycho-client (crates/tycho-client/CLAUDE.md):

• Compare module map against crates/tycho-client/src/ directory tree
• Compare connections diagram against actual struct relationships
• Compare sync lifecycle against crates/tycho-client/src/feed/synchronizer.rs

tycho-execution (crates/tycho-execution/CLAUDE.md):

• Compare Solidity architecture against crates/tycho-execution/contracts/
• Compare Rust encoding module map against crates/tycho-execution/src/ directory tree
• Compare swap flow description against actual contract entry points

protocols (protocols/CLAUDE.md, protocols/substreams/CLAUDE.md, protocols/testing/CLAUDE.md, protocols/adapter-integration/CLAUDE.md):

• Compare substreams protocol list against protocols/substreams/ subdirectories
• Compare adapter-integration protocol list against protocols/adapter-integration/evm/src/ and test/
• Verify release tagging instructions still match protocols/substreams/Readme.md

tycho-integration-test (crates/tycho-integration-test/CLAUDE.md):

• Compare module map against crates/tycho-integration-test/src/ directory tree
• Compare env vars / CLI args against Cli struct in crates/tycho-integration-test/src/main.rs
• Compare validation steps against actual logic in stream_processor/

tycho-simulation (crates/tycho-simulation/CLAUDE.md):

• Compare module map against crates/tycho-simulation/src/ directory tree
• Compare native protocol list against crates/tycho-simulation/src/evm/protocol/ subdirectories
• Compare VM adapter description against crates/tycho-simulation/src/evm/protocol/vm/
• Compare features table against crates/tycho-simulation/Cargo.toml [features]

Skill file paths: Verify every source path referenced in .claude/skills/sync-docs/SKILL.md and .claude/skills/run-ci/SKILL.md still exists.

Output format: For each discrepancy, report:

1. Which doc file is wrong
2. What the doc says vs what the code says (with file:line references)
3. Severity: HIGH (would cause agent to write wrong code) or MEDIUM (misleading but recoverable)

Agent 2: Commit Differ (subagent_type: general-purpose)

Reads the docs-synced-at commit hash from the first line of .claude/CODEBASE.md, then examines all commits between that hash and HEAD to find changes that demand documentation updates.

Prompt for Agent 2:

You are reviewing git history to find commits that may have introduced documentation drift.

1. Read the first line of .claude/CODEBASE.md to extract the commit hash from the docs-synced-at HTML comment (format: <!-- docs-synced-at: <hash> -->).
2. Run git log --oneline <hash>..HEAD -- crates/tycho-indexer/src/ crates/tycho-common/src/ crates/tycho-storage/src/ crates/tycho-ethereum/src/ crates/tycho-client/src/ crates/tycho-simulation/src/ crates/tycho-execution/src/ protocols/testing/ to list all source-code commits since the last doc sync.
3. For each commit (or group of related commits), run git diff <hash> HEAD on the relevant paths to understand what changed. Focus on:
   • New or removed files/modules under any crates/tycho-*/src/ or protocols/ directory
   • Changed trait definitions (added/removed/renamed methods) in crates/tycho-common/src/storage.rs or crates/tycho-common/src/traits.rs
   • Changed ProtocolSim trait in crates/tycho-simulation/src/ or executor interfaces in crates/tycho-execution/src/
   • Changed struct/enum definitions (added/removed/renamed fields/variants)
   • Changed RPC endpoints in crates/tycho-indexer/src/services/rpc.rs
   • Changed feature flags in any crate's Cargo.toml
   • Changed CLI commands in crates/tycho-indexer/src/cli/
   • Changed data flow or extraction pipeline logic
   • New DEX integrations added to crates/tycho-simulation/src/protocol/ or crates/tycho-execution/src/encoding/
4. For each change that affects something documented in .claude/CODEBASE.md or any CLAUDE.md, report:
   • The commit(s) that introduced the change
   • Which doc file is affected
   • What specifically changed and what the doc should say now

Ignore: test-only changes, comment changes, internal refactors that don't change public interfaces, dependency version bumps (unless a new dependency adds a new module).

Output format: A list of "doc update needed" items, each with:

1. Commit hash(es) and summary
2. Which doc file needs updating
3. What the doc currently says (if relevant)
4. What it should say based on the code change

Agent 3: Reviewer (subagent_type: general-purpose)

Waits for Agents 1 and 2 to complete, then synthesizes their findings and applies the actual documentation edits.

Prompt for Agent 3 (pass the output of Agents 1 and 2 as context):

You are the final reviewer for a documentation sync. Two agents have produced findings:

Agent 1 (Code Reader) compared docs against current source code and found discrepancies. Agent 2 (Commit Differ) reviewed git history since the last sync and found commits that demand doc updates.

Your job:

1. Deduplicate: If both agents flag the same issue, merge them into one.
2. Filter: Only keep items that would genuinely mislead an agent. Drop anything that's:
   • Minor wording differences
   • Implementation details that don't affect how an agent would use the code
   • Adding detail to something already clear enough
   • Field visibility (pub vs private) unless it affects how an agent would call the API
   • Missing async keywords on methods where async is obvious from context
3. Apply edits: For each remaining item, use the Edit tool to fix the documentation file. Keep edits minimal -- change only what's wrong, don't restructure surrounding text.
4. Update the sync marker: After all edits, update the docs-synced-at hash in .claude/CODEBASE.md line 1 to the current HEAD commit hash (run git rev-parse HEAD to get it).
5. Verify skill file paths: Check that every source path referenced in .claude/skills/sync-docs/SKILL.md and .claude/skills/run-ci/SKILL.md still exists. If any path is stale, fix it.
6. Report a summary of:
   • Files that were already accurate
   • Files that were updated and what changed
   • Any new modules not yet documented (create docs if needed)
   • Any stale paths in the skill files that were corrected

Execution

Use TaskCreate to create a task list so the user can track progress. Create these tasks up front:

Then execute:

1. Mark tasks 1 and 2 as in_progress. Launch Agent 1 (Code Reader) and Agent 2 (Commit Differ) in parallel using the Agent tool with run_in_background: true.
2. When each background agent completes, mark its task as completed.
3. Once both are done, mark task 3 as in_progress. Launch Agent 3 (Reviewer) with the combined output of Agents 1 and 2.
4. Agent 3 applies all edits and produces the final report. Mark task 3 as completed.
5. Present Agent 3's report to the user.