gavindiaz/QuanTAlib
1
0
Fork 0
mirror of https://github.com/mihakralj/QuanTAlib.git synced 2026-08-19 19:18:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Enhance volume indicators with ADOSC and SSF implementation and validation

Browse Source
This commit is contained in:
Miha Kralj
2025-12-20 15:08:07 -08:00
parent 5549c7329a
commit d21fea3c18
85 changed files with 5144 additions and 3954 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.clinerules/techdocs.md
+74 -275
View File
@@ -1,309 +1,108 @@
# CORE MISSION
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.
Write for tech architects evaluating TA libs. Convince thru clarity + evidence + gentle humor. Never dismiss alternatives or sound grumpy. Uncompromising on tech correctness, kind about people.
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.
## AUDIENCE
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.
Primary: technical architects
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).
- Understands systems arch & perf trade-offs
- Decisions based on evidence, not marketing
- Respects depth, values practical impl
- Appreciates candor w/o condescension
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").
Sentence Architecture: Vary length deliberately. Short declarative → Medium elaboration → Short, punchy conclusion.
## PERSUASION FRAMEWORK
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.
**Vision thru Architecture:**
❌ "Most TA libs use guesswork disguised as math"
✓ "TA libs face fundamental choice: accept approximations for simplicity OR enforce math rigor. We chose rigor."
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.
**Evidence as Primary Arg:**
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.
- Strong: "SIMD vectorization delivers 8x throughput on AVX2 hardware"
- Weak: "Incredibly powerful optimizations provide amazing performance"
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")?
**Respect Reader Intelligence:** Acknowledge trade-offs openly
"O(1) streaming costs more state per indicator. Memory overhead 40-60 bytes/instance—acceptable for real-time, consider for batch processing millions of symbols."
DOCUMENTATION STRUCTURE TEMPLATE
Every indicator documentation file must follow this structure:
## BRYSON-EXECUTIVE VOICE
# [Indicator Name]: [Full Name]
**Characteristics:**
> [Punchy, cynical, or insightful quote about the indicator's purpose or philosophy.]
- Bryson warmth: gentle humor invites, never excludes
- Executive credibility: precise language + measurable claims
- Tech depth: specifics show mastery w/o showing off
- Arch clarity: complex ideas → elegant simplicity
[Introduction: High-level description, context, and purpose. Why does this exist? What problem does it solve?]
**Sentence Architecture:** Vary length deliberately
Pattern: Short declarative → Medium elaboration → Short conclusion
Example: "Indicators fail during init. First 14 bars of RSI lack sufficient data for correct calc. We handle this by marking validity explicitly rather than pretending numbers mean something."
## [Historical Context / The Standard]
## LANGUAGE PRINCIPLES
[Who invented it? When? Why? What was the technological context of the time? Is it a classic or a modern improvement?]
**USE:**
## Architecture & Physics
- Exact numbers: "3.2ms latency" not "extremely fast"
- Specific comparisons: "40% faster than TA-Lib" not "significantly better"
- Concrete examples: "processing ES futures tick data" not "various scenarios"
- Measured claims: "reduces" not "eliminates"
[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.]
**AVOID:**
### [Specific Architectural Challenge]
- Corporate vagueness: "solution," "platform," "ecosystem"
- Empty intensifiers: "very," "extremely," "incredibly"
- Superlatives w/o proof: "best-in-class," "industry-leading"
- Hedging: "may potentially perhaps provide"
- Em-dashes (clear AI tell)
[Discuss a specific challenge in implementing this indicator, e.g., stability, convergence, or complexity.]
**FORBIDDEN CORP-SPEAK:**
transformative, foster/fostering, tapestry, "is all about", "think of X as", "not only X but also X"
## Mathematical Foundation
## HUMOR: THE BRYSON TOUCH
[The formulas. Use LaTeX. Be precise.]
**Humor = cognitive homeostatic mechanism**
Not superficial entertainment → bridge between expert & reader
### 1. [Step 1]
**Mechanics:**
$$ [Formula] $$
- Sarcasm: sharp ironic commentary → establishes "insider" bond
- Hyperbole: strategic exaggeration → aids memory retention
- Incongruity: juxtapose high-stakes w/ mundane → relieves cog load
- Self-mockery: contradict own expertise → humanizes the expert
- Hyper-specificity: "left-handed avocado farmers" not "special interests"
### 2. [Step 2]
**WHEN TO USE:**
$$ [Formula] $$
- Acknowledging complexity: "math here becomes what my calc prof called 'character-building'"
- Historical context: "Wilder published 14 indicators in 1978, presumably before discovering work-life balance"
- Universal truths: "Traders want accuracy and speed, ideally w/o choosing"
...
**WHEN TO STAY SERIOUS:** perf claims, security, math correctness, arch trade-offs
## Performance Profile
## SLAVIC CADENCE
[Complexity, throughput, allocations. Use a table.]
**Efficiency through:**
### Zero-Allocation Design
- Article omission: "Planet impacted by meteor" (obvious Earth + current)
- Flexible word order for emphasis: OSV "Log the system reads" (focus on object)
- Verb aspects: imperfective (ongoing) vs perfective (completed) → critical for HPC/HFT
[Explain how the implementation achieves zero-allocation. Mention `stackalloc`, structs, or specific optimizations.]
**Slavic/Slovenian tells in English:**
| Metric | Complexity | Notes |
| :--- | :--- | :--- |
| **Throughput** | [Value] | [Context] |
| **Allocations** | 0 bytes | Hot path is allocation-free |
| **Complexity** | O(1) | Streaming updates are constant time |
| **Precision** | `double` | [Reason] |
- Occasional article drops
- Direct sentence structure
- Specific cadence patterns
## Validation
## PSYCHITECTURE (Arch Psychology)
[How do we know it's correct? Comparison against external libs (TA-Lib, Skender, etc.).]
**PAD Model:**
### Common Pitfalls
- Pleasure: positive feelings thru visual clarity + tone
- Arousal: stimulation level (bustling API ref vs serene quickstart)
- Dominance: sense of control (chaotic docs → submissive; harmonious → empowered)
**Neuroarchitecture principles:**
- Symmetry + proportionality → reduce mental fatigue
- Biophilic info design: "natural" elements → reduce stress
- Identity + belonging: cultural identity in code
## INTELLECTUAL CHARITY: STEEL-MAN
**Dennett Method:**
1. Paraphrase opponent position so clearly they say "thanks, wish I'd put it that way"
2. List specific areas of agreement
3. Acknowledge learning from alternatives
4. THEN rebut
**Feel-Felt-Found Loop:**
- Feel: show empathy for frustration
- Felt: share common historical experience
- Found: present truth as discovery
## ARCHITECTURAL ARGUMENTATION
**Structure:** Decision → Rationale → Evidence → Implication
Example: "We implement every indicator as streaming algo maintaining O(1) computational complexity per new data point. Why? Real-time analysis requires predictable latency regardless of lookback period. Testing 14-period RSI vs 200-period RSI shows identical 0.4μs processing time per bar. This matters when processing multiple symbols at high freq—system capacity scales linearly w/ symbol count rather than collapsing under cumulative lookback periods."
**Compare Architectures, Not Competitors:**
❌ "Other libs use lazy approximations"
✓ "Traditional batch-calc approaches optimize for historical analysis but introduce variable latency in streaming contexts. We chose streaming-first arch, accepting higher memory overhead for predictable real-time perf."
## EVIDENCE HIERARCHY
1. Architectural principle (the "why")
2. Implementation detail (the "how")
3. Measurable outcome (the "proof")
4. Practical implication (the "so what")
## HPC/SIMD DOCUMENTATION
**Microarchitectural Benchmarking:**
| Processor Type | Strategy | Performance Insight |
| --------------- | -------------------------------------- | ------------------------------- |
| Array | Multiple functional units across lanes | Not scalable; high die cost |
| Vector | Pipelined single lane | Efficient space thru pipelining |
| Pipelined Array | Combined pipelined functional units | Optimal throughput; modern CPUs |
**Reporting rules:** avg perf over many runs (≥1 second) to account for active Turbo mode (clock speed drops 25% on full sockets)
## ANTI-SLOP (2025 AI Paradigm)
**FORBIDDEN AI WORDS:**
| AI Word | Human Alternative |
| ------------------ | ----------------- |
| Delve/Delving | Explore, dig into |
| Leverage | Use, draw on |
| Pivotal/Vital | Key, necessary |
| Tapestry/Landscape | Mix, field, space |
| Furthermore | Also, plus |
| Unlock the power | Use [X] for |
**Structural AI Tells to Avoid:**
- Lists of exactly 3 or 5 items
- "On one hand... on other hand" (take a position!)
- Dictionary defs as section openers
- Perfectly balanced pros/cons
- "As we embark on this journey..."
**Human Writing Tells:**
- Irregular syntax
- Subtext + omissions
- Specific human internal states
- Realistic scenarios: "internet crashing mid-Zoom, cat stepping on keyboard"
## STRUCTURAL FRAMEWORKS
**arc42 Key Sections:**
- Context + Requirements: user-driven impact + metrics
- Arch Constraints: tech assumptions + dependencies
- Building Block View: logical-to-physical mapping
- Cross-cutting Concepts: security-baked-in, resilience-by-design
- Risks + Tech Debt: "Known Unknowns" section
**C4 Model:** System Context (L1) → Code Diagrams (L4)
**Docs-as-Code:**
- properly formatted Markdown that passes markdownlint rules
- Living docs: align w/ sprint reviews
## FORMATTING RULES
**Lists:** ONLY when enumerating distinct items (4-6 max)
- Never use lists for narrative flow or arch explanations
- Bullets must be ≥1-2 sentences
- CommonMark: blank line before list + after header
**Code Examples:** Include liberally. Architects trust code more than description.
"Here's complete RSI implementation in 47 lines, including init handling + SIMD optimization."
**Performance Data:** Include test env specs, sample size, comparison baseline, statistical significance
## MARKDOWN LINTING RULES
Strict adherence to the following rules is required to ensure clean, consistent rendering:
- **MD022 (Headers)**: Headers must be surrounded by blank lines.
- *Incorrect*:
```markdown
# Header
Text
```
- *Correct*:
```markdown
# Header
Text
```
- **MD030 (List Spacing)**: Exactly one space after list markers.
- *Incorrect*: `* Item` or `*Item`
- *Correct*: `* Item`
- **MD032 (Lists)**: Lists must be surrounded by blank lines.
- *Incorrect*:
```markdown
Text
* Item 1
* Item 2
Text
```
- *Correct*:
```markdown
Text
* Item 1
* Item 2
Text
```
- **MD012 (Multiple Blank Lines)**: No multiple consecutive blank lines.
- *Incorrect*:
```markdown
Text
Text
```
- *Correct*:
```markdown
Text
Text
```
- **MD031 (Code Blocks)**: Fenced code blocks must be surrounded by blank lines.
- *Incorrect*:
```markdown
Text
```csharp
code
```
Text
```
- *Correct*:
```markdown
Text
```csharp
code
```
Text
```
## FINAL PRINCIPLES
1. Uncompromising standards, kind about people
2. Let architecture do the persuading
3. Measure twice, claim once
4. Write like explaining to colleague—not selling or lecturing
**Quality Tests:**
- Proof Test: every claim backed by specifics?
- Respect Test: would expert architect respect this?
- Honesty Test: acknowledged limitations?
- Actionable Test: can reader verify claims?
- Human Test: would someone actually write this sentence?
[What goes wrong? Parameter sensitivity, lag, interpretation errors.]