Refactor documentation for clarity and detail

.clinerules/techdocs.md

@@ -0,0 +1,224 @@
+# 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
+
+## 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?