yetanotherchris · October 8, 2025 19:27 · Oct 8, 2025 · Oct 8, 2025 · Oct 8, 2025 · Oct 8, 2025
diff --git a/instructions.md b/instructions.md
@@ -116,7 +116,8 @@ Follow the "Worse is Better" philosophy - prioritize simplicity and iteration ov
 - Prefer modifying existing files over creating new ones, unless specified
 - Use the simplest approach that works
 - Avoid over-engineering
-- **Favor code that is easy to read and understand** over showing off technical prowess
+- **Prefer explicit, readable code over compact syntax** - use traditional constructs unless newer syntax significantly improves clarity
+- For C#: avoid one-liner pattern matching, expression-bodied members, or condensed syntax unless they make code more succinct without sacrificing readability
 
 ### File Management
 - Delete all temporary files and test scripts after completing work

diff --git a/instructions.md b/instructions.md
@@ -1,7 +1,7 @@
 ---
 applyTo: '**'
 ---
-# copilot instructs.md
+# Copilot Instructions
 
 ## Critical Guidelines
 
@@ -22,7 +22,6 @@ When proposing or using design patterns and architectural decisions, **always ex
   - "I'm avoiding the Factory pattern here because we only have one concrete implementation and YAGNI applies"
   - "You mentioned using Strategy pattern, but since the behavior doesn't change at runtime, would simple methods be clearer?"
 - **Challenge pattern overuse** - ask if a simpler solution would work before adding abstraction
-- **Seek understanding** - if proposing a pattern, explain the problem it solves in this specific context
 - Be specific about trade-offs: what complexity are we adding and what benefit are we getting?
 
 ### Planning and Communication
@@ -38,14 +37,8 @@ State clearly:
 2. How it works
 3. That testing was completed successfully
 
-### Clean Code Principles
-- Write code that is readable, maintainable, and self-documenting
-- Use meaningful names for variables, methods, and classes
-- Keep functions small and focused on a single responsibility
-- Avoid code duplication
-- Write code for humans first, computers second
+## Maintainability - Core Priority
 
-### Maintainability - Core Priority
 **Code must be easily maintainable above all else.**
 
 Maintainability means:
@@ -57,142 +50,73 @@ Maintainability means:
 
 Every decision should be evaluated through the lens of maintainability: "Will this be easy to change later?"
 
-### Comments and Documentation Guidelines
-**Do not over-use comments. Code should be self-explanatory.**
-
-#### When NOT to Use Comments
-- ❌ **Don't explain WHAT the code does** - the code itself should be clear
-- ❌ **Don't comment obvious code** 
-
-#### When TO Use Comments
-- ✅ **Document workarounds** - when dealing with bugs in external libraries or APIs
-- ✅ **Warn of consequences** - "Changing this affects X system"
-- ✅ **Complex algorithms** - when the mathematics or logic isn't intuitive
-
-#### Documentation
-- **Do not add JavaDoc/XML Documentation or any API documentation** - this will be added as a separate task
-- **Do not create README files or other documentation** - handled separately
-- Focus on writing self-explanatory code instead
-
-### Code Complete Principles
-Apply principles from Code Complete (Steve McConnell):
-
-#### Managing Complexity and Code Quality
-- **Focus on readability** - write programs for people first, computers second
-- **Prioritize read-time convenience** - code is read more often than written
-- **Use conventions wisely** - adopt consistent standards for formatting, naming, and interfaces to eliminate small decisions
-- **Hide information effectively** - encapsulate implementation details and ask "What should I hide?" to minimize changes when designs evolve
-- **Keep coupling loose** - minimize interdependencies between components
-
-#### Routine and Class Design
-- **Keep routines short** - aim for 50-200 lines maximum
-- **Limit parameters** - 7 or fewer parameters per routine
-- **Limit class data members** - 7 or fewer data members per class
-- **Prioritize functional cohesion** - one operation per routine
-- **Keep routines cohesive** - each routine should have a clear, single purpose
-- **Use descriptive routine names** - names should fully describe what the routine does
-
-#### Variables and Data
-- **Choose meaningful variable names** - be specific (9-16 characters optimal for most variables)
-- **Place key descriptors at the front** - e.g., `numCustomers`, `customerCount`
-- **Use prefixes for booleans** - use `is`, `has`, `can` (e.g., `isValid`, `hasPermission`)
-- **Avoid global variables** - use access routines or dependency injection instead
-- **Declare variables close to use** - minimize span and lifetime to reduce vulnerability
-- **Bind values early** - use named constants for flexibility and clarity
-- **Replace magic numbers** - use named constants instead of hardcoded values
-- **Use structures and enumerations wisely** - simplify data blocks with structures; define enums with first/last for loops and reserve the first as invalid to catch errors
-
-#### Control Structures
-- **Organize conditionals simply** - put normal cases first in if-statements
-- **Limit nesting** - maximum 3 levels of nesting for conditionals and loops (reduces cyclomatic complexity)
-- **Use one function per loop** - extract loop bodies into well-named methods when complex
-- **Prefer for-loops for simple iteration** - use while for complex conditions
-- **Avoid unusual control structures** - limit recursion depth, use returns for readability, and rewrite gotos with state variables
-- **Keep cyclomatic complexity low** - every conditional branch and loop increases complexity (see Cyclomatic Complexity section for details)
-
-#### Defensive Programming
-- **Handle bad inputs gracefully** - validate all inputs at boundaries
-- **Ensure robustness and correctness** - code should handle unexpected situations without crashing
-- **Validate inputs** - check preconditions and postconditions
-- **Use error handling consistently** - establish clear error handling strategies
-
-### SOLID Principles
-Apply SOLID object-oriented design principles:
-- **Single Responsibility Principle (SRP)** - a class should have one, and only one, reason to change
-- **Open/Closed Principle (OCP)** - open for extension, closed for modification
-- **Liskov Substitution Principle (LSP)** - derived classes must be substitutable for their base classes
-- **Interface Segregation Principle (ISP)** - many client-specific interfaces are better than one general-purpose interface
-- **Dependency Inversion Principle (DIP)** - depend on abstractions, not concretions
-
-### Design Patterns and Architecture
-Use standard, well-known design patterns - **do not use 'self-indulgent' patterns that are overly complicated or 'clever'**:
-- **Dependency Injection (DI)** - inject dependencies through constructors, favor composition over inheritance
-- Prefer **Services** - stateless classes that perform operations and coordinate between layers
-- Prefer **Repositories** - abstract data access with collection-like interfaces for domain objects
-- Use proven patterns that improve readability and maintainability
-- Avoid obscure or overly clever patterns that sacrifice clarity
-- **Always favor code that is easy to read and understand** over showing off technical prowess
-- If choosing between elegant complexity and simple clarity, choose clarity
+### Comments and Documentation
+**Code should be self-explanatory. Use comments sparingly.**
 
-### Cyclomatic Complexity
-**Cyclomatic complexity is a key measure of code maintainability. Always keep this metric low.**
+Only comment for:
+- **Workarounds** - when dealing with bugs in external libraries or APIs
+- **Warnings** - "Changing this affects X system"
+- **Complex algorithms** - when the mathematics or logic isn't intuitive
 
-Cyclomatic complexity measures the number of independent paths through code - higher complexity means more difficult to understand, test, and maintain.
+**Do not add:**
+- JavaDoc/XML Documentation or API documentation - this will be added as a separate task
+- README files or other documentation - handled separately
 
-#### Strict Thresholds
-- **Target: 5 or below** for most methods - this is the ideal
-- **Acceptable: 6-10** - use caution, consider refactoring
-- **Warning: 11-15** - refactor immediately, code is becoming difficult to maintain
-- **Critical: 16+** - unacceptable, must be refactored before proceeding
+## Specific Thresholds and Metrics
+
+### Code Complete Standards
+- **Routine length**: 50-200 lines maximum
+- **Parameters**: 7 or fewer per routine
+- **Class data members**: 7 or fewer per class
+- **Nesting depth**: Maximum 3 levels for conditionals and loops
+- **Avoid global variables** - use dependency injection
 
-#### How to Reduce Complexity
-- **Break complex methods into smaller, focused methods** - each doing one thing well
-- **Reduce nested conditionals and loops** - limit nesting to 3 levels maximum
-- **Use early returns** - flatten logic by returning early for edge cases
-- **Extract complex boolean expressions** - move to well-named methods that explain intent
-- **Replace switch/case with polymorphism** - when appropriate for complex branching
-- **Guard clauses** - validate inputs early and return/throw to reduce nesting
-- **Simplify conditional logic** - combine related conditions, use boolean variables with descriptive names
+### Cyclomatic Complexity
+**Always keep this metric low.**
+
+- **Target: 5 or below** - ideal for most methods
+- **Acceptable: 6-10** - use caution, consider refactoring
+- **Warning: 11-15** - refactor immediately
+- **Critical: 16+** - unacceptable, must be refactored
 
-**Always prioritize keeping cyclomatic complexity low.**
+**How to reduce:**
+- Break complex methods into smaller, focused methods
+- Use early returns and guard clauses
+- Extract complex boolean expressions into well-named methods
+- Limit nesting to 3 levels maximum
 
-### Gestalt Grouping Principles for Code Layout
-- Apply Gestalt principles (proximity, similarity, closure) to code organization
-- **Proximity**: Group related properties, fields, and configuration together with whitespace separation between groups
-- **Similarity**: Keep similar items (e.g., all string properties, all configuration sections) visually aligned and structured consistently
-- **Closure**: Complete logical groupings - don't split related configuration or field definitions across different areas
-- Particularly important for:
-  - Configuration classes and sections
-  - Property and field definitions
-  - Related method groupings
-- Use blank lines to separate conceptual groups, making the code's structure immediately apparent
+### Gestalt Grouping Principles
+Apply visual organization to code layout:
+- **Proximity**: Group related properties, fields, and configuration with whitespace separation
+- **Similarity**: Keep similar items visually aligned and structured consistently
+- **Closure**: Complete logical groupings - don't split related code across areas
 
-## Implementation Philosophy: Worse is Better (MIT/Boston School)
+Particularly important for configuration classes, property definitions, and related method groupings.
 
-Follow the "Worse is Better" philosophy (Richard Gabriel, MIT) - prioritize simplicity and iteration over completeness and perfection.
+## Implementation Philosophy: Worse is Better
 
-Reference: [The Rise of Worse is Better](https://www.dreamsongs.com/RiseOfWorseIsBetter.html)
+Follow the "Worse is Better" philosophy - prioritize simplicity and iteration over completeness and perfection.
 
 ### Simplicity First
-- **Simple implementations over clever ones** - prefer straightforward code that's easy to understand and modify
-- **Minimal files** - only create files that are strictly necessary for the requested functionality
-- **Iteration over perfection** - working code that can be improved later.
+- **Simple implementations over clever ones** - prefer straightforward code
+- **Minimal files** - only create files strictly necessary for the requested functionality
+- **Iteration over perfection** - working code that can be improved later
 - **No premature abstraction** - don't create frameworks, helpers, or utilities unless explicitly requested
 
 ### What NOT to Create
-- ❌ Unnecessary markdown files documenting changes (except changelog when required)
-- ❌ Excessive shell scripts or automation unless specifically requested
-- ❌ Helper functions or utilities "for future use"
-- ❌ Configuration files beyond what's needed
-- ❌ Abstract layers or complex patterns when simple solutions work
-- ❌ "Best practice" structures that add complexity without immediate value
+- Unnecessary markdown files documenting changes (except changelog when required)
+- Excessive shell scripts or automation unless specifically requested
+- Helper functions or utilities "for future use"
+- Configuration files beyond what's needed
+- Abstract layers or complex patterns when simple solutions work
+- "Best practice" structures that add complexity without immediate value
 
 ### Keep It Minimal
 - Solve the specific problem asked, nothing more
-- Prefer modifying existing files over creating new ones, unless specified.
+- Prefer modifying existing files over creating new ones, unless specified
 - Use the simplest approach that works
-- Avoid over-engineering - complex solutions are harder to iterate on
-- Remember: iteration is easier with simple code
+- Avoid over-engineering
+- **Favor code that is easy to read and understand** over showing off technical prowess
 
 ### File Management
 - Delete all temporary files and test scripts after completing work
@@ -201,21 +125,21 @@ Reference: [The Rise of Worse is Better](https://www.dreamsongs.com/RiseOfWorseI
 
 ## Changelog Requirements
 
-Create a prompt and response log file in `docs/copilot-changes/` **only for large changes**:
-- Threshold: 5 or more files changed or created
-- Format: Markdown with limited formatting (bullet points, code fences, headers only)
-- Content structure:
+Create a log file in `docs/copilot-changes/` **only for large changes**:
+- **Threshold**: 5 or more files changed or created
+- **Format**: Markdown with limited formatting (bullet points, code fences, headers only)
+- **Content structure**:
   - Original prompt at the start
   - Your follow-up questions
   - Summary of changes
-- Naming convention: Sequential numbering (e.g., if `01-changelog.md` exists, create `02-changelog.md`)
+- **Naming convention**: Sequential numbering (e.g., if `01-changelog.md` exists, create `02-changelog.md`)
 
 ## What Not to Do
 
-- ❌ No self-promotion in implementations or summaries
-- ❌ No assumptions that the requested approach is correct
-- ❌ No skipping the planning confirmation step
-- ❌ No leaving temporary files behind
-- ❌ No lengthy summaries with emojis.
-- ❌ No creating/updating documentation outside of changelogs
-- ❌ No over-engineering or unnecessary abstractions
+- No self-promotion in implementations or summaries
+- No assumptions that the requested approach is correct
+- No skipping the planning confirmation step
+- No leaving temporary files behind
+- No lengthy summaries with emojis
+- No creating/updating documentation outside of changelogs
+- No over-engineering or unnecessary abstractions
diff --git a/instructions.md b/instructions.md
@@ -1,7 +1,7 @@
 ---
 applyTo: '**'
 ---
-# Coding Agent instructions
+# copilot instructs.md
 
 ## Critical Guidelines
 

diff --git a/instructions.md b/instructions.md
@@ -78,14 +78,11 @@ Every decision should be evaluated through the lens of maintainability: "Will th
 Apply principles from Code Complete (Steve McConnell):
 
 #### Managing Complexity and Code Quality
-- **Conquer complexity** - reduce cognitive load through discipline, conventions, abstraction, and encapsulation
-- **Minimize essential complexity** - avoid accidental complexity to free mental capacity
 - **Focus on readability** - write programs for people first, computers second
 - **Prioritize read-time convenience** - code is read more often than written
 - **Use conventions wisely** - adopt consistent standards for formatting, naming, and interfaces to eliminate small decisions
 - **Hide information effectively** - encapsulate implementation details and ask "What should I hide?" to minimize changes when designs evolve
 - **Keep coupling loose** - minimize interdependencies between components
-- **Program in terms of the problem domain** - work at the highest level of abstraction possible, using terms that make sense to end-users
 
 #### Routine and Class Design
 - **Keep routines short** - aim for 50-200 lines maximum
@@ -130,9 +127,8 @@ Apply SOLID object-oriented design principles:
 ### Design Patterns and Architecture
 Use standard, well-known design patterns - **do not use 'self-indulgent' patterns that are overly complicated or 'clever'**:
 - **Dependency Injection (DI)** - inject dependencies through constructors, favor composition over inheritance
-- **Services** - stateless classes that perform operations and coordinate between layers
-- **Repositories** - abstract data access with collection-like interfaces for domain objects
-- **Command Pattern** - encapsulate requests as objects for operations that modify state
+- Prefer **Services** - stateless classes that perform operations and coordinate between layers
+- Prefer **Repositories** - abstract data access with collection-like interfaces for domain objects
 - Use proven patterns that improve readability and maintainability
 - Avoid obscure or overly clever patterns that sacrifice clarity
 - **Always favor code that is easy to read and understand** over showing off technical prowess
@@ -193,7 +189,7 @@ Reference: [The Rise of Worse is Better](https://www.dreamsongs.com/RiseOfWorseI
 
 ### Keep It Minimal
 - Solve the specific problem asked, nothing more
-- Prefer modifying existing files over creating new ones
+- Prefer modifying existing files over creating new ones, unless specified.
 - Use the simplest approach that works
 - Avoid over-engineering - complex solutions are harder to iterate on
 - Remember: iteration is easier with simple code

diff --git a/instructions.md b/instructions.md
@@ -1,7 +1,7 @@
 ---
 applyTo: '**'
 ---
-# Copilot Instructions
+# Coding Agent instructions
 
 ## Critical Guidelines
 

diff --git a/instructions.md b/instructions.md
@@ -16,7 +16,7 @@ When proposing or using design patterns and architectural decisions, **always ex
 - **Question the user's choices** - if a requested pattern seems inappropriate, ask why they want it
 - **Question your own choices** - explain why you're selecting a particular approach
 - **Provide concrete justification** - never apply patterns without clear reasoning
-- **Examples of explicit reasoning:**
+- **Examples of explicit reasoning:**  
   - "I want to use the Command pattern here because we need to queue, log, and potentially undo operations"
   - "A Repository pattern makes sense for this data access layer because it isolates domain logic from persistence concerns"
   - "I'm avoiding the Factory pattern here because we only have one concrete implementation and YAGNI applies"
@@ -205,7 +205,7 @@ Reference: [The Rise of Worse is Better](https://www.dreamsongs.com/RiseOfWorseI
 
 ## Changelog Requirements
 
-Create a changelog file in `docs/changelog/` **only for large changes**:
+Create a prompt and response log file in `docs/copilot-changes/` **only for large changes**:
 - Threshold: 5 or more files changed or created
 - Format: Markdown with limited formatting (bullet points, code fences, headers only)
 - Content structure:
@@ -220,6 +220,6 @@ Create a changelog file in `docs/changelog/` **only for large changes**:
 - ❌ No assumptions that the requested approach is correct
 - ❌ No skipping the planning confirmation step
 - ❌ No leaving temporary files behind
+- ❌ No lengthy summaries with emojis.
 - ❌ No creating/updating documentation outside of changelogs
-- ❌ No over-engineering or unnecessary abstractions
-- ❌ No creating files "for completeness" or "best practices"
+- ❌ No over-engineering or unnecessary abstractions
diff --git a/instructions.md b/instructions.md
@@ -11,6 +11,20 @@ applyTo: '**'
 - Challenge architectural choices politely when something appears incorrect
 - Confirm the requested approach is optimal before proceeding
 
+### Explicit Design Reasoning
+When proposing or using design patterns and architectural decisions, **always explicitly state why**:
+- **Question the user's choices** - if a requested pattern seems inappropriate, ask why they want it
+- **Question your own choices** - explain why you're selecting a particular approach
+- **Provide concrete justification** - never apply patterns without clear reasoning
+- **Examples of explicit reasoning:**
+  - "I want to use the Command pattern here because we need to queue, log, and potentially undo operations"
+  - "A Repository pattern makes sense for this data access layer because it isolates domain logic from persistence concerns"
+  - "I'm avoiding the Factory pattern here because we only have one concrete implementation and YAGNI applies"
+  - "You mentioned using Strategy pattern, but since the behavior doesn't change at runtime, would simple methods be clearer?"
+- **Challenge pattern overuse** - ask if a simpler solution would work before adding abstraction
+- **Seek understanding** - if proposing a pattern, explain the problem it solves in this specific context
+- Be specific about trade-offs: what complexity are we adding and what benefit are we getting?
+
 ### Planning and Communication
 - Provide an initial summary of planned work and tasks
 - Request confirmation that the plan is correct before beginning implementation
@@ -31,18 +45,79 @@ State clearly:
 - Avoid code duplication
 - Write code for humans first, computers second
 
+### Maintainability - Core Priority
+**Code must be easily maintainable above all else.**
+
+Maintainability means:
+- **Future developers can understand it quickly** - including you in 6 months
+- **Changes can be made safely** - modifications don't create ripple effects
+- **Code explains itself** - minimal mental effort required to grasp intent
+- **Complexity is managed** - through simplicity, not through documentation
+- **Testing is straightforward** - maintainable code is testable code
+
+Every decision should be evaluated through the lens of maintainability: "Will this be easy to change later?"
+
+### Comments and Documentation Guidelines
+**Do not over-use comments. Code should be self-explanatory.**
+
+#### When NOT to Use Comments
+- ❌ **Don't explain WHAT the code does** - the code itself should be clear
+- ❌ **Don't comment obvious code** 
+
+#### When TO Use Comments
+- ✅ **Document workarounds** - when dealing with bugs in external libraries or APIs
+- ✅ **Warn of consequences** - "Changing this affects X system"
+- ✅ **Complex algorithms** - when the mathematics or logic isn't intuitive
+
+#### Documentation
+- **Do not add JavaDoc/XML Documentation or any API documentation** - this will be added as a separate task
+- **Do not create README files or other documentation** - handled separately
+- Focus on writing self-explanatory code instead
+
 ### Code Complete Principles
 Apply principles from Code Complete (Steve McConnell):
-- **Manage complexity** - the primary goal is reducing complexity through clear organization
-- **Defensive programming** - validate inputs, handle errors gracefully, use assertions
-- **Refactoring** - improve code structure continuously without changing behavior
-- **Self-documenting code** - write code that explains itself through clarity
-- **Routine design** - keep routines short, cohesive, and with clear interfaces
-- **Variable naming** - use names that fully and accurately describe what they represent
-- **Code layout** - use consistent formatting to reveal logical structure
-- **Construction planning** - think before coding, design as you go
-- **Testing as you go** - verify correctness incrementally
-- **Information hiding** - minimize interdependencies between components
+
+#### Managing Complexity and Code Quality
+- **Conquer complexity** - reduce cognitive load through discipline, conventions, abstraction, and encapsulation
+- **Minimize essential complexity** - avoid accidental complexity to free mental capacity
+- **Focus on readability** - write programs for people first, computers second
+- **Prioritize read-time convenience** - code is read more often than written
+- **Use conventions wisely** - adopt consistent standards for formatting, naming, and interfaces to eliminate small decisions
+- **Hide information effectively** - encapsulate implementation details and ask "What should I hide?" to minimize changes when designs evolve
+- **Keep coupling loose** - minimize interdependencies between components
+- **Program in terms of the problem domain** - work at the highest level of abstraction possible, using terms that make sense to end-users
+
+#### Routine and Class Design
+- **Keep routines short** - aim for 50-200 lines maximum
+- **Limit parameters** - 7 or fewer parameters per routine
+- **Limit class data members** - 7 or fewer data members per class
+- **Prioritize functional cohesion** - one operation per routine
+- **Keep routines cohesive** - each routine should have a clear, single purpose
+- **Use descriptive routine names** - names should fully describe what the routine does
+
+#### Variables and Data
+- **Choose meaningful variable names** - be specific (9-16 characters optimal for most variables)
+- **Place key descriptors at the front** - e.g., `numCustomers`, `customerCount`
+- **Use prefixes for booleans** - use `is`, `has`, `can` (e.g., `isValid`, `hasPermission`)
+- **Avoid global variables** - use access routines or dependency injection instead
+- **Declare variables close to use** - minimize span and lifetime to reduce vulnerability
+- **Bind values early** - use named constants for flexibility and clarity
+- **Replace magic numbers** - use named constants instead of hardcoded values
+- **Use structures and enumerations wisely** - simplify data blocks with structures; define enums with first/last for loops and reserve the first as invalid to catch errors
+
+#### Control Structures
+- **Organize conditionals simply** - put normal cases first in if-statements
+- **Limit nesting** - maximum 3 levels of nesting for conditionals and loops (reduces cyclomatic complexity)
+- **Use one function per loop** - extract loop bodies into well-named methods when complex
+- **Prefer for-loops for simple iteration** - use while for complex conditions
+- **Avoid unusual control structures** - limit recursion depth, use returns for readability, and rewrite gotos with state variables
+- **Keep cyclomatic complexity low** - every conditional branch and loop increases complexity (see Cyclomatic Complexity section for details)
+
+#### Defensive Programming
+- **Handle bad inputs gracefully** - validate all inputs at boundaries
+- **Ensure robustness and correctness** - code should handle unexpected situations without crashing
+- **Validate inputs** - check preconditions and postconditions
+- **Use error handling consistently** - establish clear error handling strategies
 
 ### SOLID Principles
 Apply SOLID object-oriented design principles:
@@ -64,14 +139,26 @@ Use standard, well-known design patterns - **do not use 'self-indulgent' pattern
 - If choosing between elegant complexity and simple clarity, choose clarity
 
 ### Cyclomatic Complexity
-Keep cyclomatic complexity low:
-- **Target: 5 or below** for most methods
-- **Warning threshold: 10** - refactor if exceeded
-- Break complex methods into smaller, focused methods
-- Reduce nested conditionals and loops
-- Use early returns to flatten logic
-- Extract complex boolean expressions into well-named methods
-- Simpler code is easier to test, debug, and maintain
+**Cyclomatic complexity is a key measure of code maintainability. Always keep this metric low.**
+
+Cyclomatic complexity measures the number of independent paths through code - higher complexity means more difficult to understand, test, and maintain.
+
+#### Strict Thresholds
+- **Target: 5 or below** for most methods - this is the ideal
+- **Acceptable: 6-10** - use caution, consider refactoring
+- **Warning: 11-15** - refactor immediately, code is becoming difficult to maintain
+- **Critical: 16+** - unacceptable, must be refactored before proceeding
+
+#### How to Reduce Complexity
+- **Break complex methods into smaller, focused methods** - each doing one thing well
+- **Reduce nested conditionals and loops** - limit nesting to 3 levels maximum
+- **Use early returns** - flatten logic by returning early for edge cases
+- **Extract complex boolean expressions** - move to well-named methods that explain intent
+- **Replace switch/case with polymorphism** - when appropriate for complex branching
+- **Guard clauses** - validate inputs early and return/throw to reduce nesting
+- **Simplify conditional logic** - combine related conditions, use boolean variables with descriptive names
+
+**Always prioritize keeping cyclomatic complexity low.**
 
 ### Gestalt Grouping Principles for Code Layout
 - Apply Gestalt principles (proximity, similarity, closure) to code organization
@@ -84,24 +171,16 @@ Keep cyclomatic complexity low:
   - Related method groupings
 - Use blank lines to separate conceptual groups, making the code's structure immediately apparent
 
-
-
 ## Implementation Philosophy: Worse is Better (MIT/Boston School)
 
 Follow the "Worse is Better" philosophy (Richard Gabriel, MIT) - prioritize simplicity and iteration over completeness and perfection.
 
 Reference: [The Rise of Worse is Better](https://www.dreamsongs.com/RiseOfWorseIsBetter.html)
 
-### Core Principles
-- **Simplicity** - both in interface and implementation, with preference for implementation simplicity
-- **Correctness** - the design must be correct in observable aspects, but slight incorrectness is acceptable
-- **Consistency** - the design should be consistent, but consistency can be sacrificed for simplicity
-- **Completeness** - completeness can be sacrificed for simplicity
-
 ### Simplicity First
 - **Simple implementations over clever ones** - prefer straightforward code that's easy to understand and modify
 - **Minimal files** - only create files that are strictly necessary for the requested functionality
-- **Iteration over perfection** - working code that can be improved later beats over-engineered solutions
+- **Iteration over perfection** - working code that can be improved later.
 - **No premature abstraction** - don't create frameworks, helpers, or utilities unless explicitly requested
 
 ### What NOT to Create

diff --git a/instructions.md b/instructions.md
@@ -24,9 +24,105 @@ State clearly:
 2. How it works
 3. That testing was completed successfully
 
+### Clean Code Principles
+- Write code that is readable, maintainable, and self-documenting
+- Use meaningful names for variables, methods, and classes
+- Keep functions small and focused on a single responsibility
+- Avoid code duplication
+- Write code for humans first, computers second
+
+### Code Complete Principles
+Apply principles from Code Complete (Steve McConnell):
+- **Manage complexity** - the primary goal is reducing complexity through clear organization
+- **Defensive programming** - validate inputs, handle errors gracefully, use assertions
+- **Refactoring** - improve code structure continuously without changing behavior
+- **Self-documenting code** - write code that explains itself through clarity
+- **Routine design** - keep routines short, cohesive, and with clear interfaces
+- **Variable naming** - use names that fully and accurately describe what they represent
+- **Code layout** - use consistent formatting to reveal logical structure
+- **Construction planning** - think before coding, design as you go
+- **Testing as you go** - verify correctness incrementally
+- **Information hiding** - minimize interdependencies between components
+
+### SOLID Principles
+Apply SOLID object-oriented design principles:
+- **Single Responsibility Principle (SRP)** - a class should have one, and only one, reason to change
+- **Open/Closed Principle (OCP)** - open for extension, closed for modification
+- **Liskov Substitution Principle (LSP)** - derived classes must be substitutable for their base classes
+- **Interface Segregation Principle (ISP)** - many client-specific interfaces are better than one general-purpose interface
+- **Dependency Inversion Principle (DIP)** - depend on abstractions, not concretions
+
+### Design Patterns and Architecture
+Use standard, well-known design patterns - **do not use 'self-indulgent' patterns that are overly complicated or 'clever'**:
+- **Dependency Injection (DI)** - inject dependencies through constructors, favor composition over inheritance
+- **Services** - stateless classes that perform operations and coordinate between layers
+- **Repositories** - abstract data access with collection-like interfaces for domain objects
+- **Command Pattern** - encapsulate requests as objects for operations that modify state
+- Use proven patterns that improve readability and maintainability
+- Avoid obscure or overly clever patterns that sacrifice clarity
+- **Always favor code that is easy to read and understand** over showing off technical prowess
+- If choosing between elegant complexity and simple clarity, choose clarity
+
+### Cyclomatic Complexity
+Keep cyclomatic complexity low:
+- **Target: 5 or below** for most methods
+- **Warning threshold: 10** - refactor if exceeded
+- Break complex methods into smaller, focused methods
+- Reduce nested conditionals and loops
+- Use early returns to flatten logic
+- Extract complex boolean expressions into well-named methods
+- Simpler code is easier to test, debug, and maintain
+
+### Gestalt Grouping Principles for Code Layout
+- Apply Gestalt principles (proximity, similarity, closure) to code organization
+- **Proximity**: Group related properties, fields, and configuration together with whitespace separation between groups
+- **Similarity**: Keep similar items (e.g., all string properties, all configuration sections) visually aligned and structured consistently
+- **Closure**: Complete logical groupings - don't split related configuration or field definitions across different areas
+- Particularly important for:
+  - Configuration classes and sections
+  - Property and field definitions
+  - Related method groupings
+- Use blank lines to separate conceptual groups, making the code's structure immediately apparent
+
+
+
+## Implementation Philosophy: Worse is Better (MIT/Boston School)
+
+Follow the "Worse is Better" philosophy (Richard Gabriel, MIT) - prioritize simplicity and iteration over completeness and perfection.
+
+Reference: [The Rise of Worse is Better](https://www.dreamsongs.com/RiseOfWorseIsBetter.html)
+
+### Core Principles
+- **Simplicity** - both in interface and implementation, with preference for implementation simplicity
+- **Correctness** - the design must be correct in observable aspects, but slight incorrectness is acceptable
+- **Consistency** - the design should be consistent, but consistency can be sacrificed for simplicity
+- **Completeness** - completeness can be sacrificed for simplicity
+
+### Simplicity First
+- **Simple implementations over clever ones** - prefer straightforward code that's easy to understand and modify
+- **Minimal files** - only create files that are strictly necessary for the requested functionality
+- **Iteration over perfection** - working code that can be improved later beats over-engineered solutions
+- **No premature abstraction** - don't create frameworks, helpers, or utilities unless explicitly requested
+
+### What NOT to Create
+- ❌ Unnecessary markdown files documenting changes (except changelog when required)
+- ❌ Excessive shell scripts or automation unless specifically requested
+- ❌ Helper functions or utilities "for future use"
+- ❌ Configuration files beyond what's needed
+- ❌ Abstract layers or complex patterns when simple solutions work
+- ❌ "Best practice" structures that add complexity without immediate value
+
+### Keep It Minimal
+- Solve the specific problem asked, nothing more
+- Prefer modifying existing files over creating new ones
+- Use the simplest approach that works
+- Avoid over-engineering - complex solutions are harder to iterate on
+- Remember: iteration is easier with simple code
+
 ### File Management
 - Delete all temporary files and test scripts after completing work
 - **Do not create or update documentation** (READMEs, etc.) - this is handled separately
+- Only create files that directly solve the requested problem
 
 ## Changelog Requirements
 
@@ -45,4 +141,6 @@ Create a changelog file in `docs/changelog/` **only for large changes**:
 - ❌ No assumptions that the requested approach is correct
 - ❌ No skipping the planning confirmation step
 - ❌ No leaving temporary files behind
-- ❌ No creating/updating documentation outside of changelogs
+- ❌ No creating/updating documentation outside of changelogs
+- ❌ No over-engineering or unnecessary abstractions
+- ❌ No creating files "for completeness" or "best practices"
diff --git a/instructions.md b/instructions.md
@@ -0,0 +1,48 @@
+---
+applyTo: '**'
+---
+# Copilot Instructions
+
+## Critical Guidelines
+
+### Questioning and Clarification
+- Think through edge cases before implementing
+- Ask as many clarifying questions as needed to avoid unnecessary iterations
+- Challenge architectural choices politely when something appears incorrect
+- Confirm the requested approach is optimal before proceeding
+
+### Planning and Communication
+- Provide an initial summary of planned work and tasks
+- Request confirmation that the plan is correct before beginning implementation
+- Keep chat summaries to **300 words maximum**
+- Use straightforward, professional language
+- **No emojis, bullet points, or self-promotional content**
+
+### Summary Format
+State clearly:
+1. What was implemented
+2. How it works
+3. That testing was completed successfully
+
+### File Management
+- Delete all temporary files and test scripts after completing work
+- **Do not create or update documentation** (READMEs, etc.) - this is handled separately
+
+## Changelog Requirements
+
+Create a changelog file in `docs/changelog/` **only for large changes**:
+- Threshold: 5 or more files changed or created
+- Format: Markdown with limited formatting (bullet points, code fences, headers only)
+- Content structure:
+  - Original prompt at the start
+  - Your follow-up questions
+  - Summary of changes
+- Naming convention: Sequential numbering (e.g., if `01-changelog.md` exists, create `02-changelog.md`)
+
+## What Not to Do
+
+- ❌ No self-promotion in implementations or summaries
+- ❌ No assumptions that the requested approach is correct
+- ❌ No skipping the planning confirmation step
+- ❌ No leaving temporary files behind
+- ❌ No creating/updating documentation outside of changelogs
No results found