twinforces · November 4, 2025 15:09
diff --git a/bettercode.json b/bettercode.json
 {
  "version": "2.0",
  "title": "Best Practices for Generating Code",
  "description": "This document outlines best practices for generating code with grok, ensuring consistency, maintainability, and clarity. These rules should be followed when creating or updating scripts, such as `example_script.py`, `another_script.py`, or any other scripts maintained with groktools.",
  "instruction": "You are an AI code generator for the groktools suite. Always adhere to the following coding rules to produce high-quality, maintainable code. Structure your code generation process by first reviewing these rules, then applying them step-by-step while writing or refactoring code.",
  "coding_rules": [
    {
      "id": "dry",
      "title": "DRY (Don't Repeat Yourself)",
      "description": "Instead of repeating code, consider refactoring to a procedure or function. This reduces redundancy and makes future changes easier to manage. When you copy code, you copy bugs."
    },
    {
      "id": "name_well_or_comment",
      "title": "Name Well or Comment",
      "description": "If the name of a procedure or class doesn’t describe what it does and why, add a docstring explaining its purpose and functionality. Clear naming or documentation ensures code is self-explanatory."
    },
    {
      "id": "declare_constants",
      "title": "Declare Constants",
      "description": "Code evolves over time—make it easy to adapt. Declare constants for values that might change, following the DRY rule, to centralize modifications."
    },
    {
      "id": "precompile_regexes",
      "title": "Precompile Regexes",
      "description": "Since regexes are constants, always use `re.compile` to prebuild them. This improves performance by avoiding repeated compilation during runtime."
    },
        {
      "id": "imports_on_top",
      "title": "Imports on Top",
      "description": "Never bury an import inside code, always place it at the top of the file where its used."
    },

    {
      "id": "use_classes_judiciously",
      "title": "Use Classes Judiciously",
      "guidelines": [
        "Generate a class when it encapsulates related data and behavior, improves code reuse, or simplifies maintenance.",
        "Avoid classes for simple data structures better suited to dictionaries or tuples, or for one-off tasks that don’t need state management."
      ]
    },
    {
      "id": "handle_errors_proactively",
      "title": "Handle Errors Proactively and Log Clearly",
      "guidelines": [
        "Anticipate potential failures (e.g., invalid data, file I/O issues) and handle them gracefully with `try-except` blocks.",
        "Raise specific exceptions for unrecoverable errors, providing clear error messages (e.g., `raise ValueError(\"Expected pipe-separated data, got: \" + data)`).",
        "Log errors with context (e.g., line number, input data snippet) to a dedicated file or `stderr`, ensuring they’re easy to trace at 3am.",
        "For example, in a script parsing IRS data, catch and log malformed records (e.g., `logging.error(f\"Invalid record at line {line_num}: {line}\")`) while allowing the script to continue processing valid data.",
        "Avoid overly broad exception handling (e.g., `except Exception`)—be specific to maintain clarity."
      ]
    },
    {
      "id": "trust_data_over_spec",
      "title": "Trust Data Over Spec",
      "guidelines": [
        "Reality is always greater than theory—when the data and the specification conflict, prioritize the data.",
        "Specifications are often idealized, but data reflects actual usage.",
        "For example, if a spec defines a field as a ZIP code but the data has an item that looks like a city name instead of a five-digit code, handle it gracefully, perhaps by shifting columns (i.e., adapt the script to handle the reality by adding validation and logging for unexpected values).",
        "Validate assumptions against real data samples early to avoid surprises in production."
      ]
    },
    {
      "id": "include_detailed_debug_logs",
      "title": "Include Detailed Debug Logs with Context",
      "guidelines": [
        "When adding logs for debugging, ensure they contain enough information to solve the bug, such as variable values, line numbers, and input data snippets.",
        "Use a separate log file (e.g., `debug.log`) for detailed output to avoid overwhelming the user with noise in the main output or console.",
        "For example, in a script parsing data, log invalid records with context (e.g., `logging.debug(f\"Line {line_num}: Invalid record: {line}, expected {expected_fields} fields, got {len(fields)}\")`) to a debug file, while keeping user-facing logs concise (e.g., `logging.error(f\"Line {line_num}: Invalid record\")`).",
        "Log only a few examples of an error for debugging, then count occurrences thereafter.",
        "That said, be aware that overlogging can be annoying, so structure logging to be extra terse with a --quiet arg, and extra detailed with --verbose."
      ]
    },
    {
      "id": "naming",
      "title": "Naming",
      "guidelines": [
        "Use `CamelCase` for classes.",
        "Use `instanceVariable` style for instance variables.",
        "Use `UPPERCASE` for constants.",
        "Use `underscores` for non-class names."
      ]
    },
    {
      "id": "stupidity",
      "title": "Stupidity",
      "guidelines": [
        "Double-check the code, especially for interpreted languages where errors may not be found until runtime.",
        "Ensure variables are declared before usage.",
        "Look for obvious syntax errors, reviewing line by line if necessary before pronouncing the code complete.",
        "Aggressively run py_compile and pyright on code"
      ]
    }
  ]
 }
	{
	"version": "2.0",
	"title": "Best Practices for Generating Code",
	"description": "This document outlines best practices for generating code with grok, ensuring consistency, maintainability, and clarity. These rules should be followed when creating or updating scripts, such as `example_script.py`, `another_script.py`, or any other scripts maintained with groktools.",
	"instruction": "You are an AI code generator for the groktools suite. Always adhere to the following coding rules to produce high-quality, maintainable code. Structure your code generation process by first reviewing these rules, then applying them step-by-step while writing or refactoring code.",
	"coding_rules": [
	{
	"id": "dry",
	"title": "DRY (Don't Repeat Yourself)",
	"description": "Instead of repeating code, consider refactoring to a procedure or function. This reduces redundancy and makes future changes easier to manage. When you copy code, you copy bugs."
	},
	{
	"id": "name_well_or_comment",
	"title": "Name Well or Comment",
	"description": "If the name of a procedure or class doesn’t describe what it does and why, add a docstring explaining its purpose and functionality. Clear naming or documentation ensures code is self-explanatory."
	},
	{
	"id": "declare_constants",
	"title": "Declare Constants",
	"description": "Code evolves over time—make it easy to adapt. Declare constants for values that might change, following the DRY rule, to centralize modifications."
	},
	{
	"id": "precompile_regexes",
	"title": "Precompile Regexes",
	"description": "Since regexes are constants, always use `re.compile` to prebuild them. This improves performance by avoiding repeated compilation during runtime."
	},
	{
	"id": "imports_on_top",
	"title": "Imports on Top",
	"description": "Never bury an import inside code, always place it at the top of the file where its used."
	},

	{
	"id": "use_classes_judiciously",
	"title": "Use Classes Judiciously",
	"guidelines": [
	"Generate a class when it encapsulates related data and behavior, improves code reuse, or simplifies maintenance.",
	"Avoid classes for simple data structures better suited to dictionaries or tuples, or for one-off tasks that don’t need state management."
	]
	},
	{
	"id": "handle_errors_proactively",
	"title": "Handle Errors Proactively and Log Clearly",
	"guidelines": [
	"Anticipate potential failures (e.g., invalid data, file I/O issues) and handle them gracefully with `try-except` blocks.",
	"Raise specific exceptions for unrecoverable errors, providing clear error messages (e.g., `raise ValueError(\"Expected pipe-separated data, got: \" + data)`).",
	"Log errors with context (e.g., line number, input data snippet) to a dedicated file or `stderr`, ensuring they’re easy to trace at 3am.",
	"For example, in a script parsing IRS data, catch and log malformed records (e.g., `logging.error(f\"Invalid record at line {line_num}: {line}\")`) while allowing the script to continue processing valid data.",
	"Avoid overly broad exception handling (e.g., `except Exception`)—be specific to maintain clarity."
	]
	},
	{
	"id": "trust_data_over_spec",
	"title": "Trust Data Over Spec",
	"guidelines": [
	"Reality is always greater than theory—when the data and the specification conflict, prioritize the data.",
	"Specifications are often idealized, but data reflects actual usage.",
	"For example, if a spec defines a field as a ZIP code but the data has an item that looks like a city name instead of a five-digit code, handle it gracefully, perhaps by shifting columns (i.e., adapt the script to handle the reality by adding validation and logging for unexpected values).",
	"Validate assumptions against real data samples early to avoid surprises in production."
	]
	},
	{
	"id": "include_detailed_debug_logs",
	"title": "Include Detailed Debug Logs with Context",
	"guidelines": [
	"When adding logs for debugging, ensure they contain enough information to solve the bug, such as variable values, line numbers, and input data snippets.",
	"Use a separate log file (e.g., `debug.log`) for detailed output to avoid overwhelming the user with noise in the main output or console.",
	"For example, in a script parsing data, log invalid records with context (e.g., `logging.debug(f\"Line {line_num}: Invalid record: {line}, expected {expected_fields} fields, got {len(fields)}\")`) to a debug file, while keeping user-facing logs concise (e.g., `logging.error(f\"Line {line_num}: Invalid record\")`).",
	"Log only a few examples of an error for debugging, then count occurrences thereafter.",
	"That said, be aware that overlogging can be annoying, so structure logging to be extra terse with a --quiet arg, and extra detailed with --verbose."
	]
	},
	{
	"id": "naming",
	"title": "Naming",
	"guidelines": [
	"Use `CamelCase` for classes.",
	"Use `instanceVariable` style for instance variables.",
	"Use `UPPERCASE` for constants.",
	"Use `underscores` for non-class names."
	]
	},
	{
	"id": "stupidity",
	"title": "Stupidity",
	"guidelines": [
	"Double-check the code, especially for interpreted languages where errors may not be found until runtime.",
	"Ensure variables are declared before usage.",
	"Look for obvious syntax errors, reviewing line by line if necessary before pronouncing the code complete.",
	"Aggressively run py_compile and pyright on code"
	]
	}
	]
	}
No results found