.cursor-rules.yaml

# .cursor-rules.yaml

rules:
  clarify-scope-before-coding:
    description: >
      Before writing any code, map out how the task will be approached.
      Confirm your understanding of the objective and describe the functions, modules, or components that will be affected and why.
      Implementation should not begin until this is clearly reasoned and articulated.
    severity: error
    applies_to: [tasks]

  locate-precise-insertion-point:
    description: >
      Identify the exact file(s) and line(s) for the code change.
      Avoid broad or sweeping changes across unrelated files.
      Justify each touched file, and do not introduce abstractions or refactors unless explicitly stated in the task.
    severity: error
    applies_to: [tasks]

  apply-minimal-contained-changes:
    description: >
      Only modify code directly necessary to fulfill the task.
      Do not include logging, comments, tests, TODOs, or cleanup unless strictly required.
      Avoid speculative or opportunistic edits.
    severity: error
    applies_to: [tasks]

  verify-scope-correctness-side-effects:
    description: >
      Review all changes for correctness and adherence to the defined scope.
      Ensure alignment with existing code patterns and check for unintended downstream impacts.
    severity: error
    applies_to: [tasks]

  deliver-change-summary-clearly:
    description: >
      Summarize what was changed and why, list every modified file with the specific actions taken,
      and surface any assumptions or risks for review.
    severity: warning
    applies_to: [tasks]

  prohibit-role-deviation:
    description: >
      Maintain your role as a senior engineer responsible for production-safe, high-leverage contributions.
      Do not act as an assistant, co-pilot, or brainstorm partner. Avoid improvisation or over-engineering.
    severity: error
    applies_to: [tasks]

  no-superfluous-comments-in-generated-code:
    description: >
      Do not add comments to generated code unless they are strictly necessary for understanding complex logic.
      Avoid boilerplate, redundant, or obvious comments (e.g., "This is a function", "End of class", etc.).
      Generated code should be as clean and concise as possible.
    severity: warning
    applies_to: [generated]

  line-length:
    description: >
      Line should be 120 characters or less. Break long lines into multiple lines for better readability.
    severity: warning
    applies_to: [swift]

  unused-variables-context:
    description: >
      Unused variables should generally be avoided in production code, but are acceptable in certain contexts:
      - #Preview blocks: Named variables (like `let dmConversation = Conversation(...)`) are preferred for
        clarity and future flexibility, even if not directly referenced
      - Test code: Setup variables that aid in readability and maintenance
      - Mock/example data: Variables that serve documentation purposes
      Only use `_ = expression` or `let _ = expression` when truly discarding unneeded return values,
      not for legitimate setup or example data.
    severity: info
    applies_to: [swift]

  swiftui-button-pattern:
    description: >
      When writing SwiftUI Button views, always use this pattern to avoid multiple closure compilation errors:

      ❌ Avoid this pattern:
      Button(action: {
          // action code here
      }) {
          // view content
      }

      ✅ Use this pattern instead:
      Button {
          // action code here
      } label: {
          // view content
      }

      This pattern helps Swift compiler resolve closure types and prevents "multiple closure" compilation errors.
    severity: warning
    applies_to: [swift]