Skip to content

Isurwars/Correlation / .agents/skills/solid-design

solid-design

Unverified

Apply SOLID principles adapted for modern C++23 high-performance scientific computing. Use when designing classes, decoupling modules, or reviewing architectural boundaries.

SOLID Architecture for Modern C++23

This skill guides the design, implementation, and refactoring of C++23 components to enforce SOLID architectural principles without incurring runtime performance penalties in scientific computing workflows.


Architectural Duality: Static vs. Dynamic Polymorphism

In Correlation, SOLID design operates on two distinct tiers:

TierTarget SubsystemsMechanismRationale
Compute TierCalculators, inner loops, math kernels, SIMD routinesStatic Polymorphism (C++20/23 Concepts, Templates, CRTP)Zero runtime overhead, full compiler inlining, no vtable pointer chasing, optimal cache locality.
Service TierFile I/O, UI ViewModels, ML potentials, CLI controllersDynamic Polymorphism (Pure Virtual Interfaces, DI)Modular decoupling, runtime pluggability, isolated unit test mockability.

1. Single Responsibility Principle (SRP)

Directives

  • Data vs Computation: Classes holding state (e.g., Trajectory, Cell, Atom) should exclusively manage lifecycle, storage invariants, and efficient memory layout (SoA/AoS). They must not implement correlation algorithms or format-specific exporters.
  • Computation vs Presentation: Calculators (RDFCalculator, ChiralityCalculator) accept input views (std::span) and return structured calculation results (DistributionProfile). They must never touch files, Slint UI components, or stdout.
  • Decompose Large Functions: Cognitive complexity must stay $\le 25$. If a method coordinates parsing, validation, computing, and logging, decompose it into focused helper classes or private pure subroutines.

2. Open/Closed Principle (OCP)

Directives

  • Generic Compute Kernels: Constrain calculation algorithms with concepts:
    template <typename T>
    concept CoordinateSource = requires(const T& source, size_t index) {
        { source.position(index) } -> std::convertible_to<Vector3D>;
        { source.size() } -> std::same_as<size_t>;
    };
    
    template <CoordinateSource Source>
    [[nodiscard]] DistributionProfile computeRDF(const Source& coords, double cutoff);
    
  • Pluggable Readers & ML Models: Subsystem services must use abstract interfaces:
    class ITrajectoryReader {
    public:
        virtual ~ITrajectoryReader() = default;
        [[nodiscard]] virtual std::expected<Frame, IOError> readNextFrame() = 0;
    };
    
    Adding a new file format parser or ML model must require adding a new class implementing the interface, with zero edits to the core analyzer orchestration logic.

3. Liskov Substitution Principle (LSP)

Directives

  • Contract Fulfillment: Subclasses must never weaken preconditions or strengthen postconditions.
  • Exception Uniformity: Implementations of an abstract interface must not throw undocumented, implementation-specific exceptions. Prefer std::expected<T, E> for recoverable errors.
  • Const Correctness Invariants: Methods marked const must not modify observable state via mutable or cast away const, nor cause hidden thread-safety hazards.

4. Interface Segregation Principle (ISP)

Directives

  • Role-Based Interfaces: Replace fat interfaces with small, focused interfaces.
    // Anti-pattern: Fat Interface forcing consumers to implement unused methods
    class ITrajectoryService {
    public:
        virtual Frame readFrame(size_t index) = 0;
        virtual void writeFrame(const Frame& frame) = 0;
        virtual void computeHistogram() = 0;
        virtual void renderSvg() = 0;
    };
    
    // Segregated: Narrow, dedicated interfaces
    class IFrameReader {
    public:
        virtual ~IFrameReader() = default;
        [[nodiscard]] virtual std::expected<Frame, IOError> readFrame(size_t index) = 0;
    };
    
    class IFrameWriter {
    public:
        virtual ~IFrameWriter() = default;
        [[nodiscard]] virtual std::expected<void, IOError> writeFrame(const Frame& frame) = 0;
    };
    
  • Lean Boundaries with std::span: Pass std::span<const Vector3D> instead of requiring the entire Trajectory or AppBackend class.

5. Dependency Inversion Principle (DIP)

Directives

  • Constructor Injection: Pass abstractions as constructor arguments.
    class TrajectoryAnalyzer {
    public:
        explicit TrajectoryAnalyzer(std::unique_ptr<ITrajectoryReader> reader,
                                    std::shared_ptr<ICalculatorEngine> engine)
            : reader_(std::move(reader)), engine_(std::move(engine)) {}
    
        [[nodiscard]] AnalysisResult run();
    
    private:
        std::unique_ptr<ITrajectoryReader> reader_;
        std::shared_ptr<ICalculatorEngine> engine_;
    };
    
  • Prohibit Hidden Singletons: Avoid global getInstance() calls within domain logic. High-level orchestrators must receive their dependencies explicitly.

Anti-Pattern Catalog

Anti-PatternSymptomRemediation
God ControllerAppBackend directly reads files, computes histograms, formats SVG, and handles Slint events.Extract dedicated services (FileReaderService, CalculationService, PlotRendererService). Inject into AppBackend.
Virtual Call in Hot LoopInterface method invoked inside #pragma omp parallel for or SIMD reduction.Convert the algorithm to a template constrained by a C++20 concept; instantiate statically.
Fat Data ModelTrajectory class contains calculation methods (calculateRDF(), calculatePDF()).Move calculation methods into independent calculator classes/functions in calculators/.
Concrete Tight CouplingCalculator creates a hardcoded XYZReader directly inside its constructor or calculation method.Pass std::span<const Vector3D> into calculator; instantiate reader externally.

SOLID Pre-Commit Checklist

  • Does every new class have a single, well-defined responsibility?
  • Are calculation routines decoupled from I/O and visualization?
  • Are performance-critical loops free of virtual function calls?
  • Are interfaces minimal and focused on a single role?
  • Are dependencies injected rather than constructed internally via raw new or singletons?
  • Does the design satisfy Cognitive Complexity $\le 25$?
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 318kUpdated Claude CodeCodexUnverifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall