convex-doctor Skill
When to use
Run convex-doctor after making substantive changes to any file in convex/. This includes schema changes, new queries/mutations/actions, and refactors.
How to run
# Quick score check
npx convex-doctor --score
# Verbose output with all findings
npx convex-doctor -v
# JSON output for programmatic analysis
npx convex-doctor --format json
Reading the output
Findings are organized by category with severity indicators:
- Error (red): Must fix. Weighted 1.2x (perf), 1.5x (correctness/security).
- Warning (yellow): Should fix or suppress with justification.
- Info (blue): Stylistic suggestions.
Category weights
| Category | Weight |
|---|---|
| Security | 1.5x |
| Correctness | 1.5x |
| Performance | 1.2x |
| Schema | 1.0x |
| Architecture | 0.8x |
| Configuration | 0.5x |
Remediation order
- Fix correctness and security errors first (highest impact on score).
- Fix performance errors next.
- Address warnings if they represent real issues.
- Suppress rules in
convex-doctor.tomlonly for documented false positives. - Never suppress a rule just to improve the score without justification.
Configuration
The project uses convex-doctor.toml in the project root. Rules are suppressed with a comment explaining the reasoning. See the file for current suppressions.
To disable a specific rule:
[rules]
"category/rule-name" = "off"
CI threshold
The project targets a minimum score of 90. The [ci] section in convex-doctor.toml enforces this:
[ci]
fail_below = 90