Safety-first autofix principles​

• Prefer small, deterministic edits.
• Avoid fixers when intent cannot be inferred with high confidence.
• Use suggest when multiple valid fixes exist.

Practical safeguards​

• Keep fixer ranges narrow and syntax-aware.
• Preserve comments and formatting boundaries.
• Test fixer output for parse validity and idempotence.

Safe autofixes improve adoption; risky autofixes undermine it.

Working model​

• Hand-author rule explanations and examples.
• Generate derived indexes/tables with repository scripts.
• Validate links and route stability in CI.

Why this matters​

A plugin can have technically correct rules and still be frustrating to adopt if documentation and preset behavior diverge. Sync automation reduces that risk, but maintainers still need to curate the narrative docs intentionally.

Instead of relying only on CI failures after a PR opens, these rules surface policy drift during local linting.

Core philosophy​

• Keep rules explicit and narrowly scoped.
• Prefer actionable diagnostics over vague policy errors.
• Treat autofix as an assistive capability, not a silent rewrite mechanism.

Why Docusaurus is part of the architecture​

A rule plugin without durable docs quickly becomes difficult to adopt. The docs site is intentionally split:

• Rule docs for consumers.
• Developer docs for maintainers.
• Generated API docs for type and surface reference.

That split keeps onboarding and long-term maintenance practical.

Design constraints​

• Keep type-checker calls targeted.
• Avoid repeated expensive lookups in hot paths.
• Fail gracefully when parser services are unavailable.

UX contract​

If a rule requires type information, documentation should state it and explain setup expectations.

Maintainers should optimize for predictable behavior and reliable performance over clever but fragile analysis.