QuanTAlib/.clinerules/techdocs.md

# CORE MISSION

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

Primary: technical architects

- Understands systems arch & perf trade-offs
- Decisions based on evidence, not marketing
- Respects depth, values practical impl
- Appreciates candor w/o condescension

## PERSUASION FRAMEWORK

**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."

**Evidence as Primary Arg:**

- Strong: "SIMD vectorization delivers 8x throughput on AVX2 hardware"
- Weak: "Incredibly powerful optimizations provide amazing performance"

**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."

## BRYSON-EXECUTIVE VOICE

**Characteristics:**

- 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

**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."

## LANGUAGE PRINCIPLES

**USE:**

- 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"

**AVOID:**

- 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)

**FORBIDDEN CORP-SPEAK:**
transformative, foster/fostering, tapestry, "is all about", "think of X as", "not only X but also X"

## HUMOR: THE BRYSON TOUCH

**Humor = cognitive homeostatic mechanism**
Not superficial entertainment → bridge between expert & reader

**Mechanics:**

- 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"

**WHEN TO USE:**

- 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

## SLAVIC CADENCE

**Efficiency through:**

- 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

**Slavic/Slovenian tells in English:**

- Occasional article drops
- Direct sentence structure
- Specific cadence patterns

## PSYCHITECTURE (Arch Psychology)

**PAD Model:**

- 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?