AI-RSI compounding wiki

This project uses a compounding RSI workflow: each cycle improves itself.

Architecture

• Raw sources: project artifacts and truth anchors (`docs/`, `tests/`, `pnpm` output, PRs).
• RSI wiki: lightweight operational notes in this repo (`CLAUDE.md`, `docs/roadmap.md`, `README.md`, close-out log).
• Schema: this section in `CLAUDE.md` that constrains update cadence, evidence, and scope rules.

Purpose

• Stop re-deriving process from memory at every cycle.
• Preserve what changed, why it changed, and what was learned.
• Keep improvements compounding rather than starting over each iteration.

Documentation as one source of truth

For AI + automation stability, we treat `docs/` Markdown as the canonical source:

• Structured sections: keep heading hierarchy and tables to make extraction deterministic.
• Metadata + IDs: include file IDs, update timestamps, checksums, and anchor IDs so agents can anchor evidence to exact versions.
• Canonical links + stable anchors: publish through `/docs` (human) and `/api/docs/manifest` + `/api/docs/content` (machine), avoiding drift between markdown and surfaces.
• Single truth rule: any process or behavior change in docs should update only `docs/...`; `/docs` and APIs re-render automatically and must be used by AI and agents as the live contract.

Iteration pattern (copy/paste ritual)

1. Ingest

Run checks, collect artifacts, and summarize outcomes.

1. Update

Make the required RSI updates (`CLAUDE.md`, `docs/roadmap.md`, `README.md`) in one pass.

1. Record

Add one close-out row with evidence references.

1. Refactor process

Add next-cycle hypothesis and known failure modes to keep learning actionable.

1. Compounding feedback

Add technical suggestions for the next cycle in a prioritized, implementation-ready form so process quality compounds from each pass.

Evidence anchors to keep

• `pnpm test`, `pnpm lint`, `pnpm build`
• `pnpm session:closeout`
• smoke/probe command outputs when available
• updated docs + close-out log rows

Health checks (lints for the workflow)

• Are evidence links still valid and attached?
• Are recurring defects being carried into the next cycle?
• Are scope-expansion items deferred until checks are clean?
• Are updates done in all three canonical docs every iteration?

Required close-out suggestion packet (minimum)

Each iteration should include all of the following in the close-out note:

1. Measured impact summary

1. Technical findings

1. Evidence-backed recommendation set

1. Next-cycle hypothesis

• What changed at the file/module level (new files, moved responsibilities, refactor boundaries).
• What behavior was preserved or intentionally changed (state transitions, error paths, API/queue contracts, route invariants).
• Any failure mode observed, and how the change altered its likelihood or blast radius.
• Any subtle coupling discovered across services, tests, or config (imports, shared env vars, retry windows, queue transitions, etc.).
• At least 3 ranked follow-up suggestions for compounding RSI in the next cycle:
• [ ] P0/P1 reliability hardening (e.g., edge condition handling, recovery behavior).
• [ ] P0/P1 test quality improvement (missing assertions, fuzz/contract gaps, negative-path coverage).
• [ ] P1/P2 maintainability hardening (decomposition, ownership boundaries, commentable invariants).
• Each suggestion must include owner + concrete measurable acceptance criterion (file names + command/test) so it can be executed with minimal ambiguity.
• One falsifiable hypothesis with a confidence score and the exact test/smoke command that validates or rejects it.

Keep this packet in `CLAUDE.md` updates as short bullets so evidence is actionable, not just declarative.

Minimal working contract

• One measurable hypothesis per cycle.
• Expand scope only after prior cycle is clean.
• Pause RSI expansion if required checks/evidence are missing.
• Keep evidence lightweight and append-only where practical.