---
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, 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** -- TVL filtering, graph updates, derived data dependencies, encoding
- **Correct interface signatures** for core traits (`Algorithm`, `GraphManager`, `ProtocolSim`)

## 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
- An endpoint path, method, or handler name that's wrong
- A struct or enum documented with fields/variants that don't exist
- A data flow step that's no longer accurate
- A CLI command or env var 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 three places:

### 1. `.claude/` directory

| File | Purpose |
|------|---------|
| `.claude/CODEBASE.md` | Workspace-level overview: module map, data flow, architecture, config, testing |
| `.claude/knowledge/rust.md` | Rust coding conventions and commands for this project |
| `.claude/knowledge/version_control.md` | Git/PR workflow for this project |
| `.claude/knowledge/typescript.md` | TypeScript client conventions and build process |

### 2. Per-crate and hub `CLAUDE.md` files

| File | Scope |
|------|-------|
| `fynd-core/CLAUDE.md` | Core solving logic: algorithms, worker pools, graph, feed, derived data, encoding |
| `fynd-rpc/CLAUDE.md` | HTTP RPC server: API handlers, builder, config, protocol fetching |
| `fynd-rpc-types/CLAUDE.md` | Shared DTO types for the RPC API |
| `clients/CLAUDE.md` | Hub doc: Rust client (`clients/rust/`) + TypeScript client (`clients/typescript/`) |
| `tools/CLAUDE.md` | Hub doc: fynd-benchmark + fynd-swap-cli |
| `tools/benchmark/CLAUDE.md` | Benchmark tooling detail: load test, compare, scale |

### 3. Architecture docs

| File | Purpose |
|------|---------|
| `docs/ARCHITECTURE.md` | Full architecture diagram, component descriptions, threading model |

## Process

This skill runs 3 agents: two in parallel for discovery, then one to apply fixes.

### 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 and TypeScript source code in a Cargo
> workspace. Do NOT edit any files. Only report discrepancies.
>
> For each doc file below, read it, then read the corresponding source files and report any concrete
> discrepancy that would mislead an agent.
>
> **Workspace entrypoint** (`.claude/CODEBASE.md`):
> - Compare "Workspace Module Map" against actual crates in `Cargo.toml` `[workspace.members]`
> - Compare env vars table against actual usage (search for `env::var` / `std::env`)
> - Compare CLI commands against `src/cli.rs`
> - Compare testing section against CI config (`.github/workflows/ci.yaml`)
> - Compare data flow diagram against `fynd-core/src/feed/`, `fynd-core/src/worker_pool/`,
>   `fynd-core/src/worker_pool_router/`
>
> **Architecture** (`docs/ARCHITECTURE.md`):
> - Compare component descriptions against actual source locations
> - Compare threading model against actual code
> - Compare API endpoints against `fynd-rpc/src/api/`
>
> **Knowledge docs**:
> - `.claude/knowledge/rust.md` — verify commands match `check.sh` and `.github/workflows/ci.yaml`
> - `.claude/knowledge/typescript.md` — verify against `clients/typescript/` structure
>
> **Per-crate and hub docs**:
> - `fynd-core/CLAUDE.md` — compare module map against `fynd-core/src/` directory tree
> - `fynd-rpc/CLAUDE.md` — compare against `fynd-rpc/src/` directory tree
> - `fynd-rpc-types/CLAUDE.md` — compare against `fynd-rpc-types/src/`
> - `clients/CLAUDE.md` — compare Rust client section against `clients/rust/src/`, TypeScript section against `clients/typescript/`
> - `tools/CLAUDE.md` — compare against `tools/benchmark/src/` and `tools/fynd-swap-cli/src/`
> - `tools/benchmark/CLAUDE.md` — compare module listing against `tools/benchmark/src/`
>
> **Skill files**: 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 -- fynd-core/src/ fynd-rpc/src/ fynd-rpc-types/src/ clients/ tools/ src/`
>    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 `*/src/` directory
>    - Changed trait definitions (added/removed/renamed methods) in `fynd-core/src/algorithm/` or `fynd-core/src/graph/`
>    - Changed struct/enum definitions (added/removed/renamed fields/variants)
>    - Changed RPC endpoints in `fynd-rpc/src/api/`
>    - Changed CLI commands in `src/cli.rs`
>    - Changed data flow or feed/worker pipeline logic
>    - Changed TypeScript client interfaces or OpenAPI spec
> 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:

| Task | Subject                          | Active Form                         |
|------|----------------------------------|-------------------------------------|
| 1    | Audit docs against source code   | Auditing docs against source code   |
| 2    | Review git history for doc drift | Reviewing git history for doc drift |
| 3    | Apply documentation fixes        | Applying documentation fixes        |

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.
