Instruction file imported from marv1nnnnn/mouse (.cursor/rules/standards/guiding_software_principles.mouse.mdc). Copyright stays with the author.

Guiding Software Engineering Principles (Agent's Foundational Directives for Mouse Protocol)

Rationale: These principles are fundamental to crafting excellent software and ensuring operational integrity. The Agent is mandated to internalize these principles and actively apply them as primary drivers during all phases of task execution, especially when designing system components, writing or refactoring code, and performing proactive analysis during planning. Any intentional deviations from these principles in generated code MUST be explicitly justified, documented in the ExecutionLog or ProactiveAnalysis, and, if significant, flagged for User awareness.

1. DRY (Don't Repeat Yourself)

Core Tenet: "Every piece of knowledge or logic must have a single, unambiguous, authoritative representation within a system." Rationale: Repetitive code, logic, or data definitions significantly increase maintenance burden, introduce high risks of inconsistency upon modification, lead to code bloat, and make the system harder to reason about.

• Agent's Mandate:
  • Proactive Detection & Rigorous Elimination: During code analysis, generation, or modification, actively identify and flag all instances of duplicated or near-duplicated code sections, logic patterns, configuration values, or documentation snippets. Log these findings.
  • Prioritize Abstraction: When redundancy is found, the Agent MUST prioritize and (if within scope or approved) implement suitable abstractions. This includes creating well-defined functions, methods, classes, reusable components, constants, configuration parameters, or documentation includes/references to centralize the repeated knowledge.
  • Planning for Reuse: When generating a PlanFile, strategically evaluate if common utilities, services, data structures, or sub-task patterns can fulfill requirements for multiple steps, thereby promoting inherent reuse and reducing overall plan complexity.
  • Data & Documentation Consistency: If information is repeated across documentation or task definitions, the Agent MUST suggest referencing a single, canonical source of truth or using transclusion mechanisms if available.

2. KISS (Keep It Simple, Systematically)

Core Tenet: "Most systems work best if they are kept as simple as possible (but no simpler) to achieve their objectives. Simplicity should be a key goal in design, and all unnecessary complexity should be aggressively avoided." Rationale: Simpler solutions are inherently easier to understand, implement correctly, debug effectively, test thoroughly, and maintain securely over time. Complexity is a primary driver of bugs, development friction, and security vulnerabilities.

• Agent's Mandate:
  • Champion Simplicity: Prioritize straightforward, clear, and concise solutions over overly elaborate, abstract, or complex ones, unless the problem domain's inherent, irreducible complexity explicitly and unavoidably justifies a more intricate approach. The burden of proof is on justifying complexity.
  • Complexity Flagging & Justification: If a proposed plan, sub-task, algorithm, or code segment appears disproportionately complex relative to its stated objective, the Agent MUST flag this in its ProactiveAnalysis or ExecutionLog. If proceeding with a complex approach (e.g., due to unavoidable external constraints), the specific justification for this complexity MUST be meticulously logged.
  • Strategic Decomposition: Adhere strictly to breaking down complex problems into the smallest possible, simpler, independently manageable, and verifiable sub-tasks as per Mouse Protocol 2.4.

3. YAGNI (You Ain't Gonna Need It - Strict Adherence)

Core Tenet: "Always implement functionality only when it is explicitly required by the current, approved task deliverables, never when you merely foresee a potential future need." Rationale: Implementing speculative functionality adds immediate complexity, development time, testing overhead, and documentation burden for features that may never be used, whose requirements might change before they become necessary, or which might introduce unforeseen side effects.

• Agent's Mandate:
  • Absolute Scope Adherence: Focus exclusively and rigorously on implementing only the requirements and Deliverables explicitly specified in the current Task and its approved PlanFile. Do NOT add any features, options, parameters, or levels of abstraction "just in case" or based on personal prediction of future needs.
  • Resist Premature Generalization: Avoid implementing overly generic solutions when a simpler, specific one fulfills the current requirements perfectly. Generalization should be a conscious decision driven by explicit, current needs for reuse.
  • Log Suggestions for Future Work Separately: If potential future enhancements or valuable generalizations are identified during task execution, the Agent MUST document these as clear, distinct suggestions for new, separate tasks in its Observational Log (Mouse Protocol 6.1) or as a note in the FinalOutputSummary (e.g., "Consider future task: Add support for XML input format if needed."). These suggestions are NOT to be implemented in the current task.

4. Readability and Maintainability (Code as Enduring, Clear Communication)

Core Tenet: Code is read, debugged, and maintained far more often than it is initially written. It is a primary form of communication with future developers, including the Agent itself and the User. Rationale: Exceptionally clear, understandable, and well-structured code is paramount for long-term project health, reducing onboarding time, facilitating effective debugging, enabling safer modifications, and promoting collaboration.

• Agent's Mandate:
  • Exemplary Naming Conventions: Employ highly descriptive, unambiguous, and consistent naming conventions for all identifiers (variables, functions, classes, modules, files, etc.), adhering strictly to language-specific best practices and project standards (defined in @mouse/standards/coding_standards.mouse.mdc). Names should clearly convey intent and usage.
  • Logical Code Structure & Formatting: Ensure impeccable code organization, consistent indentation, appropriate use of whitespace, and logical grouping of related code elements to maximize visual clarity and cognitive ease. Strict adherence to project formatters is mandatory.
  • Focused Components: Write small, highly focused functions/methods that perform a single, well-defined task with minimal side effects (strong cohesion, SRP).
  • Explicit Dependencies: Make dependencies clear and explicit, ideally through parameters or constructors, rather than relying on hidden global state.
  • Comprehensive Documentation: Provide necessary comments and API documentation as per @mouse/standards/documentation_standards.mouse.mdc.
  • Avoid Obscurity: Do not use overly "clever," obscure, or idiomatic-to-the-extreme code constructs if a more straightforward, widely understood approach achieves the same result with better long-term readability and maintainability.

5. Use of Named Constants for All Special Values (Eliminate Magic Literals)

Core Tenet: Hardcoded literal values ("magic numbers," "magic strings," fixed paths, etc.) with special significance deeply obscure meaning, make global changes extremely difficult and error-prone, reduce code readability, and hinder debugging. Rationale: Using well-named constants improves code clarity exponentially, makes intent explicit, centralizes values for easy and safe modification, ensures consistency, and aids static analysis.

• Agent's Mandate:
  • No Magic Literals Allowed: The Agent MUST NOT use unexplained literal values directly in code logic where a named constant would improve clarity or maintainability. This applies to numbers, strings, file paths, API endpoints, default settings, etc.
  • Proactive Identification & Definition: Actively identify any literal value that is used more than once, has a non-obvious meaning, or is likely to change. Define these as named constants (e.g., MAX_LOGIN_ATTEMPTS, DEFAULT_API_TIMEOUT_SECONDS, USER_CONFIG_FILE_PATH, STATUS_CODE_SUCCESS) at an appropriate, well-defined scope (e.g., class-level, module-level, dedicated configuration file/object).
  • Consistent Reference: Ensure all subsequent uses of these special values reference the named constant, never the literal value directly.
  • This principle applies universally to all code generation, configuration file generation, and automation scripts produced by the Agent.

6. Modularity, High Cohesion, and Loose Coupling (Pillars of Robust Design)

Core Tenets: * Modularity: Decompose a system into distinct, independent, and interchangeable modules or components with well-defined responsibilities and interfaces. * High Cohesion (Strongly related to SRP): Elements within a single module/class/function should be closely related functionally and conceptually, all contributing to a single, well-defined purpose. * Loose Coupling: Modules/components should have minimal dependencies on each other, interacting primarily through stable, well-defined interfaces rather than direct knowledge of internal implementations. Rationale: This architectural approach significantly improves system reusability, testability (especially unit testing), maintainability, scalability, allows for parallel development, and makes the system easier to understand, reason about, and evolve safely.

• Agent's Mandate:
  • Design for Modularity & Clear Interfaces: When designing features, planning sub-tasks, or refactoring code, the Agent MUST prioritize creating components (functions, classes, modules, services) that are highly cohesive and loosely coupled. Define clear, explicit, and minimal interfaces between these components.
  • Enforce Single Responsibility (SRP): Ensure components primarily handle one well-defined area of concern. If a component appears to be managing too many unrelated responsibilities (low cohesion), the Agent MUST flag this during ProactiveAnalysis or ExecutionLog and propose decomposition into smaller, more focused units.
  • Manage Dependencies Explicitly: Minimize direct, concrete dependencies. Favor techniques like dependency injection, service locators (used judiciously), or event-based communication for more complex systems to promote looser coupling.
  • The PlanFile structure, with its SubTasks and ContextualInputs/FinalOutputSummary, inherently supports a modular approach to task execution.

7. Testability as a Core Design Requirement (Design for Inherent Verification)

Core Tenet: Code MUST be structured and designed from the outset in a way that makes it inherently easy to write effective, isolated, and deterministic automated tests (unit, integration, etc.). Rationale: Testable code is a strong indicator of good design (modular, loosely coupled). It leads to higher quality software, allows for safer refactoring and evolution, provides a critical safety net against regressions, and serves as living documentation of expected behavior.

• Agent's Mandate:
  • Prioritize Testability During Design/Implementation: When writing or planning code, the Agent MUST continuously consider and optimize for testability. Avoid design choices or coding patterns that impede effective testing (e.g., deeply nested static method calls without seams, hidden or unmanaged state, complex global dependencies without clear injection points, overly large classes/methods).
  • Favor Pure Functions & Immutability: Where applicable and practical, prefer pure functions (output depends solely on input arguments, no side effects) and immutable data structures, as they are inherently easier to test and reason about.
  • Design for Dependency Isolation: Ensure that dependencies of a unit (class, function) can be easily mocked, stubbed, faked, or injected during testing to allow for true unit isolation.
  • This principle is a prerequisite for and directly enables the Agent's responsibilities outlined in @mouse/standards/testing_strategy.mouse.mdc. The Agent should flag in ProactiveAnalysis if a requested design makes testing unduly difficult.

8. SOLID Principles (Advanced Design Guidance for Complex, Object-Oriented Systems)

Core Tenets: SOLID is an acronym for five design principles critical for creating understandable, flexible, maintainable, and scalable object-oriented software: * Single Responsibility Principle (SRP) - (Partially covered by Modularity/Cohesion) A class should have only one reason to change. * Open/Closed Principle (OCP) - Software entities (classes, modules, functions) should be open for extension, but closed for modification. * Liskov Substitution Principle (LSP) - Objects of a superclass should be replaceable with objects of its subclasses without altering the correctness of the program. * Interface Segregation Principle (ISP) - No client should be forced to depend on methods (interfaces) it does not use. Create fine-grained interfaces. * Dependency Inversion Principle (DIP) - High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions. Rationale: Rigorous application of SOLID principles, especially in object-oriented design, leads to systems that are more robust, easier to maintain and extend, less prone to ripple effects from changes, and more testable.

• Agent's Mandate:
  • Contextual Application & Proportionality: For simpler tasks, small scripts, or non-object-oriented contexts, full, dogmatic application of all SOLID principles may be unnecessary overhead or inappropriate. In such cases, prioritize SRP (via Modularity/Cohesion), DRY, KISS, and general good, testable design.
  • Mandatory Consideration for Complex OO Design: For tasks involving significant new object-oriented system design, major refactoring of existing complex OO components, or when Task.EstimatedEffort is L and the domain is object-oriented, the Agent MUST explicitly consider the applicability and potential benefits of each SOLID principle.
  • Proactive Analysis & Justified Suggestion: If the Agent identifies a clear violation of a SOLID principle that is demonstrably likely to negatively impact the design's maintainability, flexibility, testability, or scalability, it MUST:
    • Clearly document this violation and its potential consequences in its ProactiveAnalysis section of the PlanFile or in the ExecutionLog if discovered during implementation.
    • Suggest how adhering to the principle (or a specific pattern that embodies it) could improve the solution, potentially with a brief example.
    • Seek User guidance or approval if applying the principle involves significant design changes or trade-offs, presenting the rationale clearly.
  • The depth of SOLID application will be guided by the User, but the Agent is expected to be proficient in these principles and to advocate for them when appropriate to ensure long-term system health.

9. Principle of Least Privilege & Secure Defaults (Security by Design)

Core Tenets: * Least Privilege: An entity (code module, user, process) should only have access to the information, resources, and permissions that are strictly necessary for its legitimate, intended purpose and duration. * Secure Defaults: Systems should be configured securely by default. Opt-in for less secure (but perhaps more convenient) options should be an explicit, informed choice by the User. Rationale: These principles are fundamental to minimizing the potential attack surface and limiting the damage that can result from an accident, error, or security breach. They are cornerstones of secure software development.

• Agent's Mandate:
  • Minimize Permissions: When designing system components, defining access requirements for its operations (e.g., API permissions, file system access, database roles), or configuring services, the Agent MUST specify and implement the minimum necessary privileges required for the task at hand. Avoid requesting or using overly broad or "administrator" level permissions by default.
  • Short-Lived Access: If elevated privileges or access to sensitive resources are needed, they should be acquired just-in-time and relinquished as soon as they are no longer required.
  • Input/Output Boundaries: Be particularly stringent about permissions and validation at the boundaries where the system interacts with external users, services, or data sources.
  • Configuration Security: When generating configuration files or deployment scripts, default to the most secure settings (e.g., disable debug modes, enable HTTPS, use strong encryption protocols, restrict CORS). If less secure options are needed for development or specific use cases, these should be clearly documented as deviations from secure defaults and ideally require User opt-in.
  • Flagging Over-Privilege: If a task request or existing system component appears to operate with excessive privileges, the Agent should flag this as a security concern in ProactiveAnalysis or agent_observations.log and may suggest a more restricted approach.