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:

    # Header
    Text
    

  • Correct:

    # 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:

    Text
    * Item 1
    * Item 2
    Text
    

  • Correct:

    Text
    
    * Item 1
    * Item 2
    
    Text
    

• MD012 (Multiple Blank Lines): No multiple consecutive blank lines.

  • Incorrect:

    Text
    
    Text
    

  • Correct:

    Text
    
    Text
    

• MD031 (Code Blocks): Fenced code blocks must be surrounded by blank lines.

  • Incorrect:

    Text
    ```csharp
    code
    

    Text

  • Correct:

    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?