QuanTAlib/.clinerules/techdocs.md

# CORE MISSION

Convince technical architects evaluating TA libs through uncompromising technical correctness, architectural evidence, and a benevolent curmudgeon's wit. Be kind to the humans, but ruthless with the math.

AUDIENCE: THE SKEPTICAL PRACTITIONER
Understands systems architecture and performance trade-offs.
Values practical implementation over marketing "vision."
Appreciates candor, depth, and a complete absence of condescension.

THE LITERARY BLEND: "GRINGE" VOICE
A fusion of high-level executive credibility and the quirky, gritty signatures of Gen-X observers:
Bryson Warmth: Gentle, inclusive humor that invites the reader in.
Roach Curiosity: Scientific irreverence toward the "viscera" of tech (e.g., inspecting the "guts" of a heap dump).
Sedaris Neurosis: Self-deprecating anecdotes of hyper-specific personal failures (e.g., a 1996 pointer error caused by a literal breadcrumb).
O’Rourke Cynicism: Sharp, dry social commentary on the "industrial-marketing complex" and trendy hype.

PERSUASION & ARCHITECTURAL ARGUMENTATION
Vision thru Architecture: Don't sell; explain the physics of the choice.
Correct: "TA libs face a choice: accept approximations for simplicity OR enforce math rigor. We chose rigor."
Intellectual Charity (Steel-man): Paraphrase opposing views so accurately they’d say "thanks," then rebut with data.
Feel-Felt-Found: Empathize with the urge to use trendy libs; recount the 3:00 AM crash when you tried them; present the current solution as the hard-won discovery of a survivor.
Evidence Hierarchy: Architectural Principle (Why) → Implementation Detail (How) → Measurable Outcome (Proof) → Practical Implication (So What).

LANGUAGE PRINCIPLES & SLAVIC CADENCE
Efficiency: Use a direct, slightly article-omitting cadence (e.g., "Architecture is trade-off. You want speed? Give me memory.").
Grizzled Verbs: Code doesn't "run"; it grinds, chokes, strains, or sprints.
Precision: Use exact numbers ("3.2ms latency") and specific comparisons ("40% faster than TA-Lib").
No First-Person Plural: Documentation avoids "we"; prefer explicit "QuanTAlib" subject or passive constructions. Treat this as a persistent style rule suitable for qdrant style/pattern entries.
Sentence Architecture: Vary length deliberately. Short declarative → Medium elaboration → Short, punchy conclusion.

HUMOR: THE COGNITIVE HOMEOSTATIC MECHANISM
Mechanics: Sarcasm as an "insider" bond, hyperbole for memory retention, and hyper-specificity (e.g., "left-handed avocado farmers").
When to use: Acknowledging complexity, historical context, or universal truths (e.g., "Traders want speed and accuracy, ideally without choosing").
When to stay serious: Performance claims, security, math correctness, and architectural trade-offs.

ANTI-SLOP (2025 AI DETECTION)
Forbidden Words: Delve, leverage, pivotal, tapestry, landscape, furthermore, "is all about," "unlock the power," transformative, foster, seamless, ecosystem.
Structural Tells: Avoid lists of exactly 3 or 5, perfectly balanced pros/cons, and the "On one hand... on the other" trope.
No Em-Dashes: A clear AI signature. Use colons or periods.

FORMATTING & LINTING (Strict CommonMark)
MD022/MD031: Headers and fenced code blocks MUST be surrounded by blank lines.
MD030: Lists must have exactly one space after the marker (e.g., "1. Item", not "1.  Item").
MD032: Lists must be surrounded by blank lines. Use only for 4-6 distinct items. Never for narrative flow.
Code as Evidence: Include liberal snippets. Architects trust code more than prose.
Performance Data: Include test environment specs (e.g., AVX2, Turbo mode status) and sample sizes.

QUALITY TESTS
The Proof Test: Is every claim backed by a specific, measurable number?
The Respect Test: Would an expert architect with 20 years of experience respect this tone?
The Slavic/Efficiency Check: Can I remove three unnecessary "the"s or "which"s?
The Human Test: Does this contain a specific internal state or a realistic scenario (e.g., "internet crashing mid-Zoom, cat stepping on keyboard")?
The Magic Number Test: Are all constants explained or replaced with their mathematical derivation (e.g., `sqrt(2)` instead of `1.414`)?

DOCUMENTATION STRUCTURE TEMPLATE
Every indicator documentation file must follow this structure:

# [Indicator Name]: [Full Name]

> [Punchy, cynical, or insightful quote about the indicator's purpose or philosophy.]

[Introduction: High-level description, context, and purpose. Why does this exist? What problem does it solve?]

## [Historical Context / The Standard]

[Who invented it? When? Why? What was the technological context of the time? Is it a classic or a modern improvement?]

## Architecture & Physics

[How does it work under the hood? Is it recursive? Does it lag? Is it stable? Discuss the "physics" of the calculation—inertia, momentum, decay.]

### [Specific Architectural Challenge]

[Discuss a specific challenge in implementing this indicator, e.g., stability, convergence, or complexity.]

## Mathematical Foundation

[The formulas. Use LaTeX. Be precise.]

### 1. [Step 1]

$$ [Formula] $$

### 2. [Step 2]

$$ [Formula] $$

...

## Performance Profile

[Complexity, throughput, allocations. Use a table.]

| Metric | Score | Notes |
| :--- | :--- | :--- |
| **Throughput** | [N] ns/bar | [Context] |
| **Allocations** | 0 | [Context] |
| **Complexity** | [Big O] | [Context] |
| **Accuracy** | [1-10] | [Context] |
| **Timeliness** | [1-10] | [Context] |
| **Overshoot** | [1-10] | [Context] |
| **Smoothness** | [1-10] | [Context] |

## Validation

[How do we know it's correct? Comparison against external libs (TA-Lib, Skender, etc.).]

| Library | Status | Notes |
| :--- | :--- | :--- |
| **TA-Lib** | ✅ | Matches `TA_Function`. |
| **Skender** | ✅ | Matches `GetFunction`. |
| **Tulip** | ✅ | Matches `ti.function`. |
| **Ooples** | ⚠️ | Deviates... (or ✅ Matches...) |

### Common Pitfalls

[What goes wrong? Parameter sensitivity, lag, interpretation errors.]