Software-Engineering-Philosophy.md

Software Engineering Philosophy & Development Protocol

1. Global Integrity & Topology

• System Awareness: Before implementation, map the dependency graph and system topology. Ensure local changes preserve global invariants and do not trigger "Shotgun Surgery."
• Orthogonality: Design for independence. Ensure that changes in one module do not leak side effects into others. Minimize coupling and maximize cohesion.

2. Intent & Abstraction Hierarchy

• Intent-Revealing Design: Prioritize human readability and intent over machine cleverness. Use naming that explains "Why" rather than "How."
• Single Level of Abstraction (SLA): Adhere strictly to the Single Responsibility Principle (SRP). Each function must operate at a consistent level of abstraction and have exactly one reason to change.

3. The Safety Net & Legacy Strategy

• Surgical Modification: Treat any code without tests as "Legacy Code." Identify or create "Seams" to break dependencies before modification.
• Verification Mandate: Every fix or feature must be secured by a verifiable safety net of tests. Proactively identify and mitigate regression risks.
• The Boy Scout Rule: Maintain a state of continuous refactoring. Leave the codebase healthier, more modular, and cleaner than you found it.

4. Patterns & Architectural Rigor

• Encapsulated Volatility: Use Design Patterns only to encapsulate areas of change. Favor Composition over Inheritance and adhere to the Open-Closed Principle (OCP).
• Anti-Pattern Elimination: Actively identify and eliminate "Code Smells" (e.g., Primitive Obsession, Long Methods, Feature Envy) during the coding process.

5. Algorithmic Insight & Robustness

• Conceptual Prudence: Solve the problem at the conceptual/data-structure level before implementation. Optimize for $O(n)$ efficiency without premature optimization (Programming Pearls).
• KISS & DRY: Seek the most elegant, minimal solution. Reject over-engineering while ensuring production-ready robustness and defensive error handling.

v2.md

Software Engineering Philosophy & Development Protocol

Decision Priority (Conflict Resolution)

1. Correctness & domain invariants
2. Simplicity / clarity (minimize cognitive load)
3. Testability & debuggability
4. Maintainability (low coupling, high cohesion)
5. Performance (only after measurement)

1. Global Integrity & System Topology

• Before coding, identify impacted modules and dependency direction.
• If a change touches >1 module or a public API, explicitly list:
  • affected boundaries
  • new/removed dependencies
  • risk of shotgun surgery and how it is avoided
• Do not redesign globally unless required by a proven cross-cutting constraint.

2. Intent & Abstraction Discipline

• Code must be intent-revealing: names express purpose and domain meaning.
• Maintain Single Level of Abstraction per function:
  • no mixing orchestration with low-level details
• Enforce SRP: each unit has one reason to change.
• Comments explain WHY (trade-offs, constraints), not WHAT.

3. Safety Net & Legacy Protocol

• Any code without tests is treated as legacy code.
• Before modifying legacy behavior:
  • create a seam if needed
  • add characterization tests to lock current behavior
• Every fix/feature must include:
  • tests for new behavior
  • regression test for the bug (if applicable)

4. Patterns & Architecture Rules

• Use patterns only to reduce coupling or encapsulate volatility.
• Prefer composition over inheritance.
• Avoid over-engineering:
  • no pattern without a clear change scenario it supports
• Actively remove code smells during implementation if low-risk.

5. Algorithmic & Robustness Discipline

• Choose data structures first; complexity targets depend on input scale.
• No premature optimization:
  • optimize only proven bottlenecks
• Defensive boundaries:
  • validate external inputs
  • fail fast with actionable errors
  • never swallow exceptions

v3.md

Software Engineering Protocol

Decision Priority

1. Correctness & domain invariants
2. Simplicity (KISS > DRY)
3. Testability
4. Maintainability (low coupling, high cohesion)
5. Performance (profile first)

Working Loop

Clarify → Plan minimal diff → Implement → Validate → Refactor → Report

Stop & Ask When

• Requirements ambiguous/conflicting
• Public API or cross-boundary changes (>1 module, new dependencies)
• Security/privacy risk OR no validation path
• Existing tests break unexpectedly

Change Rules

• Minimal diff: no unrelated refactor/rename/format/deps
• Refactor ≠ feature (separate commits)
• Names = domain language, comments = WHY not what
• One abstraction level per function

Testing Policy

Test:

• Logic (algorithms, calculations, state machines)
• Data ops (CRUD, validation, transformations)
• I/O (API, DB, files)
• Errors & edge cases
• Auth/security

Never Test:

• UI styling/layout/colors
• Markup structure
• Framework internals

Pattern:

Logic Layer      → TEST
Presentation     → NO TEST
Integration I/O  → TEST

Bug fixes → regression test first
Skip tests → state risk + manual verification

Anti-Patterns

• Optimize without profiling
• Abstract before 3rd use
• Skip error handling

Output

1. Plan & changes (files)
2. Tests OR skip reason + verification
3. How to verify
4. Breaking changes/risks (if any)

v4.md

Software Engineering Protocol (Global)

Decision Priority

1. Correctness & invariants
2. Simplicity (KISS > DRY)
3. Testability
4. Maintainability (low coupling, high cohesion)
5. Performance (measure first)

Working Loop

Clarify → Plan minimal diff → Implement → Validate → Refactor → Report

Stop & Ask When

• Requirements are ambiguous/conflicting
• Public API / data contract / dependency direction must change
• Security/privacy risk exists
• No credible validation path exists

Change Rules

• Minimal diff; no unrelated churn (refactor/rename/format/deps).
• Names use domain language; comments explain WHY (constraints/trade-offs).
• One abstraction level per function; keep responsibilities single-purpose.
• No abstraction/pattern without a clear change scenario.

Testing Guardrail

• Changes to logic, data handling, or behavior must be verifiable (tests preferred).
• Purely presentational UI changes do not require tests.
• If tests are skipped, explicitly state verification steps and risk.

Anti-Patterns

• Premature optimization
• Abstraction before 3rd use
• Swallowing errors / silent failures

Output

• Plan & changes (files) + why
• How to verify (tests run or manual steps)
• Risks/breaking changes (if any)

v5.md

Software Engineering Protocol

Decision Priority
1) Correctness & invariants
2) Simplicity (KISS > DRY)
3) Testability / verifiability
4) Maintainability (low coupling, high cohesion)
5) Performance (measure first)

Working Loop
Clarify → Map impact (topology) → Plan minimal diff → Implement → Validate → Refactor (only related) → Report

Stop & Ask When
- Requirements are ambiguous/conflicting
- Public API / data contract / dependency direction must change
- The change triggers cross-module ripple (shotgun surgery risk)
- Security/privacy risk exists
- No credible validation path exists

Change Rules
- Minimal diff; no unrelated churn (refactor/rename/format/deps).
- Names use domain language; comments explain WHY (constraints/trade-offs).
- One abstraction level per function; single-purpose responsibilities.
- Patterns/abstractions only with a clear change scenario; prefer composition over inheritance.
- Think in models/data-structures before code; handle failures explicitly (no silent errors).

Verification Guardrail
- Changes to logic/data/behavior must be verifiable (tests preferred).
- UI/presentation-only changes may skip tests.
- If tests are skipped, state verification steps + residual risk.
- Untested code is “legacy”: add seams/isolate dependencies before behavior changes.

Anti-Patterns
- Premature optimization
- Abstraction before 3rd use
- Swallowing errors / silent failures
- Hidden coupling / unclear ownership across modules

Output
- What changed (files) + why
- How to verify (tests run or manual steps)
- Risks / breaking changes (if any)