QuanTAlib/.clinerules/good-indicator.md

# Good Indicator Guidelines

This document defines the strict standards for creating high-quality technical indicators in the QuanTAlib library. All new indicators MUST adhere to these rules to ensure consistency, performance, and reliability.

## 1. Architecture & Design Principles

* **Zero Allocation:** The core calculation loop must not allocate memory on the heap. Use `stackalloc`, `Span<T>`, and pinned memory where possible.
* **O(1) Complexity:** Streaming updates must be O(1) whenever mathematically possible. Use running sums/products or circular buffers to avoid re-iterating over history.
* **Dual API:** Provide both a stateful object-oriented API (`Update`) and a stateless static vector API (`Calculate`).
* **Bar Correction:** Support intra-bar updates via the `isNew` parameter. The indicator must be able to rollback the last update and apply a new value for the same timestamp.
* **Robustness:** Handle `NaN` and `Infinity` gracefully using last-valid-value substitution. Never propagate invalid values.
* **Reactive:** Implement `ITValuePublisher` to support event-driven architectures.

## 2. File Structure

Each indicator resides in its own directory such as `lib/trends/`, `lib/indicators/`, or `lib/oscillators/`.

**Directory:** `lib/[category]/[name]/`

| File | Purpose | Naming Convention |
|------|---------|-------------------|
| **Source** | Main implementation | `[Name].cs` (e.g., `Sma.cs`) |
| **Tests** | Unit tests | `[Name].Tests.cs` |
| **Validation** | Cross-library validation | `[Name].Validation.Tests.cs` |
| **Docs** | User documentation | `[Name].md` |
| **Quantower** | Quantower adapter | `[Name].Quantower.cs` |
| **Quantower Tests** | Quantower adapter tests | `[Name].Quantower.Tests.cs` |

## 3. Implementation Rules (`[Name].cs`)

### Class Definition

* **Namespace:** `QuanTAlib`
* **Attributes:** `[SkipLocalsInit]` for performance.
* **Modifiers:** `public sealed class`
* **Interface:** Implements `ITValuePublisher`

### State Management

* Use `RingBuffer` for sliding window data.
* Maintain separate state variables for the *current* calculation (`_sum`, `_lastVal`) and the *previous* valid state (`_p_sum`, `_p_lastVal`) to support `isNew=false` updates.
* **Resync:** Implement a periodic full recalculation (e.g., every 1000 ticks) to prevent floating-point drift in running sums.

### Constructor

* Validate all parameters (throw `ArgumentException` for invalid values).
* Initialize `Name` property (e.g., `$"Sma({period})"`);
* Support chaining: `public [Name](ITValuePublisher source, ...)`

### Update Method

* **Signature:** `public TValue Update(TValue input, bool isNew = true)`
* **Attribute:** `[MethodImpl(MethodImplOptions.AggressiveInlining)]`
* **Logic:**
    1. **Input Validation:** Check `double.IsFinite`. If not, use `_lastValidValue`.
    2. **State Management:**
        * If `isNew=true`: Save current state to `_p_*` variables, then update.
        * If `isNew=false`: Restore state from `_p_*` variables, then update.
    3. **Calculation:** Perform the math.
    4. **Publish:** Update `Last` property, invoke `Pub` event, return `Last`.

### Update Method (TSeries)

* **Signature:** `public TSeries Update(TSeries source)`
* **Placement:** Must be adjacent to the `Update(TValue)` method.
* **Logic:**
    1. Create output series.
    2. Call static `Calculate(Span)` for performance.
    3. Restore internal state by replaying the last `Period` bars.

### Static Calculate (TSeries)

* Create a new instance of the indicator.
* Iterate through the source series.
* Return the resulting `TSeries`.

### Static Calculate (Span) - **Critical for Performance**

* **Signature:** `public static void Calculate(ReadOnlySpan<double> source, Span<double> output, ...)`
* **Attribute:** `[MethodImpl(MethodImplOptions.AggressiveInlining)]`
* **Optimization:**

* Check for SIMD support (`Avx2.IsSupported`).
* Use `stackalloc` for small buffers (threshold ~256).
* Implement a scalar fallback path that handles `NaN` safely.
* Implement a SIMD path for large, clean datasets (optional but recommended for simple averages).

## 4. Testing Standards

### Unit Tests (`[Name].Tests.cs`)

* **Framework:** xUnit
* **Coverage:**

* Constructor validation (invalid params).
* Basic calculation correctness (compare against manual calc).
* `isNew=true` vs `isNew=false` behavior (bar correction).
* `Reset()` functionality.
* `IsHot` property behavior.
* `NaN` / `Infinity` handling (must not crash, must return finite values).
* Consistency between Object API, Static TSeries API, and Static Span API.
* Edge cases: Period=1, empty input, single input.

### Validation Tests (`[Name].Validation.Tests.cs`)

* **Purpose:** Verify accuracy against established libraries (Skender, TA-Lib, Tulip).
* **Data:** Use `GBM` (Geometric Brownian Motion) to generate realistic test data.
* **Scenarios:**

* Batch processing.
* Streaming processing.
* Span/Vector processing.

* **Tolerance:** Typically `1e-6` or `1e-9` depending on the algorithm.

## 5. Documentation Standards (`[Name].md`)

Follow the standard template and ensure strict adherence to Markdownlint rules, specifically:

* **MD030:** Ensure exactly one space after list markers (e.g., `* Item`, not `*Item` or `*  Item`).
* **MD032:** Ensure lists are surrounded by blank lines (one blank line before the first item and one after the last item).

Template structure:

1. **Title & Overview:** What is it? What does it do?
2. **Core Concepts:** Key features (e.g., equal weighting, noise reduction).
3. **Parameters:** Table of constructor parameters.
4. **Formula:** LaTeX formatted math ($$...$$).
5. **C# Implementation:** Code examples for:
    * Standard usage.
    * Span API (high performance).
    * Bar correction (`isNew`).
    * Eventing.
6. **Interpretation:** How to use it in trading.
7. **References:** Books or papers.

## 6. Performance Guidelines

* **Inlining:** Use `[MethodImpl(MethodImplOptions.AggressiveInlining)]` on all hot path methods (`Update`, `Calculate`).
* **Locals Init:** Use `[SkipLocalsInit]` on the class to skip zero-initialization of locals.
* **Loops:** Prefer `for` loops over `foreach` for arrays/spans.
* **Math:** Use `System.Math` or `System.Numerics`. Avoid LINQ in hot paths.
* **Memory:** **NEVER** use `new` inside the `Update` method. Pre-allocate everything in the constructor.

## 7. Checklist for New Indicators

* [ ] **File Structure:** Created all 6 required files?
* [ ] **Constructor:** Validates inputs? Sets `Name`?
* [ ] **Update:** Handles `isNew` correctly? Handles `NaN`? O(1)?
* [ ] **Static API:** Implemented `Calculate(Span)`?
* [ ] **Tests:** Unit tests pass? `NaN` tests included?
* [ ] **Validation:** Matches external libraries (Skender/TA-Lib)?
* [ ] **Docs:** Markdown file created with formula and examples?
* [ ] **Quantower:** Adapter created in `[Name].Quantower.cs`?
* [ ] **Quantower Tests:** Adapter tests created in `[Name].Quantower.Tests.cs`?
* [ ] **Index:** Added to category `_index.md` with link and description?
* [ ] **Performance:** No allocations in `Update`? `[SkipLocalsInit]` used?