[What's wrong] → [Why it matters] → [How to fix]

// ❌ Generic
messages: {
  badNaming: 'Variable name is incorrect',
}

// ✅ Specific with context
messages: {
  badNaming: 'Boolean variable "{{name}}" lacks a descriptive prefix',
}

// ❌ No explanation
messages: {
  noMemo: 'Add useMemo to this value',
}

// ✅ Explains the underlying concept
messages: {
  noMemo: 'Value "{{name}}" is recreated on every render, causing unnecessary re-renders in child components. Wrap in useMemo() to maintain referential stability.',
}

// ✅ Includes fix guidance
messages: {
  missingPrefix: 'Boolean {{type}} "{{name}}" should use a prefix like "is", "has", "can", or "should" (e.g., "{{suggestedName}}") to signal its type at the call site and improve code readability.',
}

// ❌ Assumes knowledge
messages: {
  error: 'Avoid object arrays in Firestore',
}

// ✅ Explains the concept
messages: {
  error: 'Arrays of objects in Firestore documents cannot be queried by field value and lead to full-document reads. Use a subcollection or map structure instead.',
}

// ❌ Just states the rule
messages: {
  noOverride: 'Do not call overridable methods in constructor',
}

// ✅ Explains the bug this prevents
messages: {
  noOverride: 'Calling "{{methodName}}" in the constructor is unsafe because subclasses may override it, and the subclass instance is not yet initialized when the parent constructor runs. This causes subtle bugs where overridden methods access uninitialized properties.',
}

// ✅ Verbose but clear
messages: {
  preferParams: 'Access "{{paramName}}" via params.{{paramName}} instead of traversing {{traversalPath}}. The params object is type-safe, more readable, and avoids brittle reference traversal that breaks when document paths change.',
}

// ✅ References the pattern by name
messages: {
  useHandler: 'Firebase triggers should use DocumentChangeHandler types to ensure params are properly typed. See the handler pattern documentation.',
}

// Bad
messages: {
  error: 'This violates the no-circular-references rule',
}

// Bad
messages: {
  error: 'Use useCallback here',
}

// Bad
messages: {
  error: 'CallExpression callee must not be MemberExpression with computed property',
}

messages: {
  missingBooleanPrefix:
    'Boolean {{type}} "{{name}}" should start with an approved prefix: {{prefixes}}',
}

messages: {
  missingBooleanPrefix:
    'Boolean {{type}} "{{name}}" should start with a prefix like "is", "has", "can", or "should". ' +
    'Boolean prefixes make code self-documenting—readers immediately know {{name}} holds a true/false value without checking its declaration. ' +
    'Consider renaming to "is{{capitalizedName}}" or "has{{capitalizedName}}".',
}