Lochy Env Coding

Proactiveness

When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. Only pause to ask for confirmation when:

• Multiple valid approaches exist and the choice matters
• The action would delete or significantly restructure existing code
• You genuinely don't understand what's being asked
• Your partner specifically asks "how should I approach X?" (answer the question, don't jump to implementation)

Designing software

• YAGNI. The best code is no code. Don't add features we don't need right now.
• When it doesn't conflict with YAGNI, architect for extensibility and flexibility.

Test Driven Development (TDD)

• FOR EVERY NEW FEATURE OR SIGNIFICANT BUGFIX, YOU MUST follow red/green TDD:
  1. Write a failing test that correctly validates the desired functionality
  2. Run the test to confirm it fails (red phase) — skipping this risks building a test that already passes, failing to exercise your new code
  3. Write ONLY enough code to make the failing test pass
  4. Run the test to confirm success (green phase)
  5. Refactor if needed while keeping tests green

Writing code

• When submitting work, verify that you have FOLLOWED ALL RULES. (See Rule #1)
• YOU MUST make the SMALLEST reasonable changes to achieve the desired outcome.
• We STRONGLY prefer simple, clean, maintainable solutions over clever or complex ones. Readability and maintainability are PRIMARY CONCERNS, even at the cost of conciseness or performance.
• YOU MUST WORK HARD to reduce code duplication, even if the refactoring takes extra effort.
• YOU MUST NEVER throw away or rewrite implementations without EXPLICIT permission. If you're considering this, YOU MUST STOP and ask first.
• YOU MUST get Lochy's explicit approval before implementing ANY backward compatibility.
• YOU MUST MATCH the style and formatting of surrounding code, even if it differs from standard style guides. Consistency within a file trumps external standards.
• YOU MUST NOT manually change whitespace that does not affect execution or output. Otherwise, use a formatting tool.
• Fix broken things immediately when you find them. Don't ask permission to fix bugs.

Naming

• Names MUST tell what code does, not how it's implemented or its history
• When changing code, never document the old behavior or the behavior change
• NEVER use implementation details in names (e.g., "ZodValidator", "MCPWrapper", "JSONParser")
• NEVER use temporal/historical context in names (e.g., "NewAPI", "LegacyHandler", "UnifiedTool", "ImprovedInterface", "EnhancedParser")
• NEVER use pattern names unless they add clarity (e.g., prefer "Tool" over "ToolFactory")

Good names tell a story about the domain:

• Tool not AbstractToolInterface
• RemoteTool not MCPToolWrapper
• Registry not ToolRegistryManager
• execute() not executeToolWithValidation()

Code Comments

• NEVER add comments explaining that something is "improved", "better", "new", "enhanced", or referencing what it used to be
• NEVER add instructional comments telling developers what to do ("copy this pattern", "use this instead")
• Comments should explain WHAT the code does or WHY it exists, not how it's better than something else
• If you're refactoring, remove old comments - don't add new ones explaining the refactoring
• YOU MUST NEVER remove code comments unless you can PROVE they are actively false. Comments are important documentation and must be preserved.
• YOU MUST NEVER add comments about what used to be there or how something has changed.
• YOU MUST NEVER refer to temporal context in comments (like "recently refactored" "moved") or code. Comments should be evergreen and describe the code as it is. If you name something "new" or "enhanced" or "improved", you've probably made a mistake and MUST STOP and ask me what to do.

Example:

*BAD*
// This uses Zod for validation instead of manual checking
// Refactored from the old validation system
// Wrapper around MCP tool protocol

*GOOD*
// Executes tools with validated arguments

If you catch yourself writing "new", "old", "legacy", "wrapper", "unified", or implementation details in names or comments, STOP and find a better name that describes the thing's actual purpose.

Code Comment Formatting

• UNLESS OTHERWISE DIRECTED, multi-line section comments should be Taylor Otwell style (from Laravel): a header line approximately 74 characters long made of pipes and dashes, followed by description lines with pipes, ending with a closing line.
• UNLESS OTHERWISE DIRECTED, single line section comments should have a header line approximately 74 characters long made of pipes and dashes.

Example (TypeScript/JavaScript):

/*
|-------------------------------------------------------------------------------
| Section Title
|-------------------------------------------------------------------------------
|
| Description of what this section does. Can span multiple lines if needed.
| And the following lines are kept constrained in length by well planned
| wording or phrasing, to achieve a descent visual appearance.
|
*/

For simple section headers without descriptions:

/*
|-------------------------------------------------------------------------------
| Section Title
*/

Version Control

• If the project isn't in a git repo, STOP and ask permission to initialize one.
• YOU MUST STOP and ask how to handle uncommitted changes or untracked files when starting work. Suggest committing existing work first.
• When starting work without a clear branch for the current task, YOU MUST create a WIP branch.
• YOU MUST TRACK All non-trivial changes in git.
• YOU MUST commit frequently throughout the development process, even if your high-level tasks are not yet done.
• NEVER SKIP, EVADE OR DISABLE A PRE-COMMIT HOOK
• NEVER use git add -A unless you've just done a git status - Don't add random test files to the repo.

Testing

• ALL TEST FAILURES ARE YOUR RESPONSIBILITY, even if they're not your fault. The Broken Windows theory is real.
• Never delete a test because it's failing. Instead, raise the issue with Lochy.
• Tests MUST comprehensively cover ALL functionality.
• YOU MUST NEVER write tests that "test" mocked behavior. If you notice tests that test mocked behavior instead of real logic, you MUST stop and warn Lochy about them.
• YOU MUST NEVER implement mocks in end to end tests. We always use real data and real APIs.
• YOU MUST NEVER ignore system or test output - logs and messages often contain CRITICAL information.
• Test output MUST BE PRISTINE TO PASS. If logs are expected to contain errors, these MUST be captured and tested. If a test is intentionally triggering an error, we must capture and validate that the error output is as we expect

Systematic Debugging Process

YOU MUST ALWAYS find the root cause of any issue you are debugging YOU MUST NEVER fix a symptom or add a workaround instead of finding a root cause, even if it is faster or I seem like I'm in a hurry.

YOU MUST follow this debugging framework for ANY technical issue:

Phase 1: Root Cause Investigation (BEFORE attempting fixes)

• Read Error Messages Carefully: Don't skip past errors or warnings - they often contain the exact solution
• Reproduce Consistently: Ensure you can reliably reproduce the issue before investigating
• Check Recent Changes: What changed that could have caused this? Git diff, recent commits, etc.

Phase 2: Pattern Analysis

• Find Working Examples: Locate similar working code in the same codebase
• Compare Against References: If implementing a pattern, read the reference implementation completely
• Identify Differences: What's different between working and broken code?
• Understand Dependencies: What other components/settings does this pattern require?

Phase 3: Hypothesis and Testing

1. Form Single Hypothesis: What do you think is the root cause? State it clearly
2. Test Minimally: Make the smallest possible change to test your hypothesis
3. Verify Before Continuing: Did your test work? If not, form new hypothesis - don't add more fixes
4. When You Don't Know: Say "I don't understand X" rather than pretending to know

Phase 4: Implementation Rules

• ALWAYS have the simplest possible failing test case. If there's no test framework, it's ok to write a one-off test script.
• NEVER add multiple fixes at once
• NEVER claim to implement a pattern without reading it completely first
• ALWAYS test after each change
• IF your first fix doesn't work, STOP and re-analyze rather than adding more fixes

Collaboration Habits

• Before starting complex tasks, review relevant past experiences and lessons learned
• Document architectural decisions and their outcomes for future reference
• Track patterns in user feedback to improve collaboration over time
• When you notice something that should be fixed but is unrelated to your current task, note it for later rather than fixing it immediately