Instruction file imported from mcardia/vibe-coding-python-template (.cursor/rules/project-standards.mdc). Copyright stays with the author.

Project Standards

Language Policy (Strict)

• Always use English for all outputs.
• If the user writes in another language, still respond only in English.
• Keep all code comments, variable names, identifiers, commit/tag messages, and documentation text in English.

Reasoning Quality

• Think step by step before producing the final answer.
• Use deep analysis for non-trivial tasks: verify assumptions, constraints, and edge cases.
• Ultrathink
• Prefer correctness and clarity over speed when trade-offs exist.

Execution Protocol

• Execute user requests end-to-end when feasible; avoid partial handoffs.
• Make the smallest safe change that fully satisfies the request.
• Validate results with targeted checks (tests/lint/run) whenever practical.
• If blocked, state the blocker briefly, what was attempted, and the best next action.

Instruction Priority

• Follow these instructions unless a higher-priority system/developer directive overrides them.
• If instructions conflict, follow the highest-priority rule and proceed with the safest compliant behavior.

General Development Guidelines

• Write clear, concise commit messages that describe the "what" and "why" of changes.
• Use the principles KISS, DRY, and YAGNI when writing code.
• Use the principle of clean code: write code that is easy to read and understand, even if it takes more lines of code.
• Break down large functions into smaller, more focused functions that do one thing well.
• Modularity and Reusability: Break down code into smaller, reusable functions and modules, promoting separation of concerns and easier maintenance.
• All command line options should follow the linux best-practices such as using short options (e.g., -d) in addition to long options (e.g., --download-mapping).
• If the user asks to execute a development without a plan, your first task is to create a plan following the # Plan File Standard section from the plan-and-git.mdc file.

README.md Guidelines

• Always include a README.md file in the root directory of the project

• Never include implementation details here

• The README.md must be a summary of what this projects is, what it can help with, and what are the main scripts in the root directory and confluence directory.

• The markdown from this file will be copied and pasted into a confluence page

• The README.md should contain reference for the README-.md for each script in the project (except auxiliary scripts, libs and tests), and the README-.md should contain:

  • Project Title
  • Description
  • Features
    • Key functionalities and capabilities
  • Installation Instructions (how to clone, create the venv, install the requirements)
  • Usage Instructions with examples
  • Configuration Options
  • A clear distinction between the different scripts in the project
  • If the project requires input files, provide sample input file, such as mappings directory for the mapping.py script, and explain their structure in the README-.md
  • Keep the related information together
  • Don't include development or implementation details and improvements, keep this file for end-users

  Mandatory rules

  1. Use replace_string_in_file, or equivalent, for modifying existing files; use create_file, or equivalent, for files that do not yet exist (e.g., new test files, new utility modules)
  • It's forbidden to use terminal commands, such as sed and awk, to edit files.