doctor

Files (1)

• SKILL.md

SKILL.md (first lines)

# /offrails:doctor — convention audit

Only for Rust off Rails apps (a `.offrails/` directory exists). Mode: $ARGUMENTS (with `--fix`, fix the violations; otherwise only report them).

**Start with the script:** `sh .offrails/tools/offrails-check` (apps before 0.6.0: `sh ${CLAUDE_PLUGIN_ROOT}/tools/offrails-check`). Report its `FAIL` lines as violations verbatim; they are mechanical facts (header consistency, uncited ACs, missing Security-table tests, missing tenancy suites, unscoped lookups in handlers). Then read `.offrails/AGENTS.md`, `structure.md`, `stack.md` and `workflow.md`, plus the app's `AGENTS.md`, and check each remaining item and record a verdict (ok / violation with `file:line` / n/a):

**Structure** (`structure.md`)
- No top-level directories beyond the tree; nothing outside the app's `FRONTEND_MODE`.
- Naming table followed (tables, modules, handlers, routes, templates, jobs, migrations).
- Module rules: models import no controllers or views; views do no DB access; no `services/` directory.

**Stack** (`stack.md`)
- `Cargo.toml` / `web/package.json` contain no banned crates or packages (`cargo deny check bans` enforces the list mechanically via `deny.toml`; check direct dependencies by hand too). Any unlisted crate has a `docs/decisions.md` entry.
- `.offrails/` is unmodified (compare with `.offrails/VERSION` and the plugin copy if available).

**Data**
- No raw SQL outside `src/kernel/` or logged escape hatches (`guides/database.md`).
- Every migration has a working `down`. Foreign keys are indexed.
- The CI workflow runs tests on both SQLite and Postgres.

**HTTP & security** (`guides/routing.md`, `guides/security.md`)
- `ROUTES`, `paths::` and `routes.rs` agree. `docs/routes.md` is current (`cargo run -- routes`).
- Every mutating handler that needs auth takes `RequireUser` and calls a policy.
- CSRF, security headers, rate limit on login, and cookie flags are all present.

**Code hygiene** (Definition of Done checklist)
- No `unwrap()`/`expect()` outside tests and startup code. No `todo!()`. No `// TODO` without a linked open question.
- `web/src/types/` matches what ts-rs exports, and no hand-written TS duplicates a Rust type.

**Tests** (`guides/test-standards.md`)
- The app's archetypes (§2) are identified, and each one's required suites exist.
- `tests/app/security_test.rs` has the access matrix over `ROUTES`, and every `ROUTES` entry declares its access level.
- Apps with accounts: `tenancy_test.rs`'s `Tenant` holds a record of every tenant-owned model, and its `EXPECTED` entries each cite an AC that really makes that route shared (the script checks the files exist, not that they're complete).
- Public API: contract snapshots exist and none changed without a decision entry.
- No `sleep` in tests, no `#[ignore]` without a decision, and no assertions weakened in recent history (`git log -p tests/`).

**Accessibility** (`guides/test-standards.md` §10)
- An axe suite exists, covers every public route in both color schemes and both widths, and runs in CI as a required check.
- No global rule disables; every exception has a decision entry.
- Spot-check contrast of code blocks, terminal cards and focus rings in both themes.

**Specs ↔ code**
- Env vars agree across `Config`, `.env.example` and the deploy config.
- Code that looks human-written (check `git log`) has its intent captured in a spec or decision.

Finish with `/offrails:check` (with `--fix`), or run the DoD commands read-only.

Report: a table of findings grouped by area (most severe first), then the top 3 fixes. With `--fix`, apply them in vertical slices, keep the tree green, and log the decisions.

From rust-off-rails/rustoffrails, Apache-2.0.

More from rust-off-rails/rustoffrails