Documentation System

September 15, 2026 · View on GitHub

ripr uses Diataxis so docs answer the reader's immediate problem instead of mixing tutorials, references, and design arguments in one place.

Front-door catalog: LIBRARY.md organizes accumulated knowledge into three shelves — agentic learnings, repo domain learnings, and repo learnings over time — with annotated links to canonical docs and a timeline of major learning milestones. Start there when orienting to the codebase.

Tutorials

Tutorials help a new user succeed once.

Current and planned tutorial docs:

Quickstart - first-hour paths for VS Code, CI, CLI, and agent or reviewer handoff
First successful PR workflow - one Rust PR, one repairable gap, one focused proof, one receipt
First successful PR demo - fixture-backed boundary, output-contract, no-action, and blocked start-here cases
Editor install to first PR - VS Code install/open through setup diagnosis, repair, receipt, and first-pr packet
Editor actionable gap queue - VS Code current repair queue, repair packet, repo gap map, and no-action states
Editor first run to first receipt - install/open, diagnose setup, repair one Rust gap, verify, receipt, refresh
Editor first-pr bridge workflow - local handoff from receipt and refresh to first-pr start-here packet
RIPR swarm human workflow - one bounded actionable-gap repair attempt from packet to receipt and outcome
Start-here surface convergence proposal - cross-surface plan for making editor, CLI, PR/CI, receipts, and preview promotion use the same safe next-action unit
Editor adoption assurance proposal - Lane 3 plan for compatibility, active root, multi-root, and fail-closed first-use diagnosis
Editor actionable gap queue proposal - Lane 3 plan for projecting existing actionable-gaps artifacts as a read-only editor repair queue
README quick start
future first-extension-install walkthrough
future first-fixture walkthrough

How-To Guides

How-to guides solve concrete tasks.

Current how-to docs:

Reference

Reference docs define stable commands, schemas, config, and enum meanings.

Current reference docs:

Planned reference docs:

SARIF output reference
LSP diagnostic code reference

Templates:

Explanation

Explanation docs record why the product and architecture are shaped this way.

Current explanation docs:

README Rule

The README is the front door. It should stay problem-first and include:

what ripr is
what question it answers
where it fits against coverage and mutation testing
quick start
current capability state
important metrics and engineering status
links to the deeper docs

Avoid turning the README into the full roadmap or full schema reference.

Index Check

Run:

cargo xtask check-doc-index

The check verifies that spec and ADR indexes list current files and that README and this documentation map still point at the active planning, metrics, spec, ADR, and PR automation docs.