sinapse-ai 1.0.0

package/squad-growth/knowledge-base/analytics-event-taxonomy.md

@@ -0,0 +1,157 @@
+# Knowledge Base: Analytics Event Taxonomy
+
+## Naming Convention
+```
+Format: object_action
+Case: snake_case
+Examples: page_view, button_click, form_submit, purchase_complete
+```
+
+### Rules
+1. **Object first, action second** — `video_play` not `play_video`
+2. **snake_case only** — no camelCase, no hyphens
+3. **Past tense for completed actions** — `form_submitted`, `purchase_completed`
+4. **Present tense for ongoing** — `video_playing`, `page_scrolling`
+5. **Max 40 characters** — concise but descriptive
+6. **No PII in event names** — never include user data
+
+## Event Categories
+
+### 1. Lifecycle Events
+| Event | Trigger | Parameters |
+|-------|---------|-----------|
+| session_start | First hit of session | session_id, source, medium |
+| first_visit | User's first ever visit | — |
+| sign_up | Account creation complete | method (google, email, apple) |
+| login | Successful login | method |
+| logout | User logs out | — |
+
+### 2. Engagement Events
+| Event | Trigger | Parameters |
+|-------|---------|-----------|
+| page_view | Page loads | page_title, page_location, page_referrer |
+| scroll | User scrolls 25/50/75/90% | percent_scrolled |
+| click | Any tracked click | element_id, element_class, link_url |
+| file_download | File download starts | file_name, file_extension |
+| video_start | Video begins playing | video_title, video_provider, video_duration |
+| video_progress | Video reaches 25/50/75% | video_title, video_percent |
+| video_complete | Video reaches 100% | video_title, video_duration |
+| search | Internal site search | search_term, results_count |
+
+### 3. E-commerce Events (GA4 Standard)
+| Event | Trigger | Parameters |
+|-------|---------|-----------|
+| view_item_list | Product list viewed | item_list_id, item_list_name, items[] |
+| select_item | Product clicked from list | item_list_id, items[] |
+| view_item | Product detail page viewed | items[], currency, value |
+| add_to_wishlist | Added to wishlist | items[], currency, value |
+| add_to_cart | Added to cart | items[], currency, value |
+| remove_from_cart | Removed from cart | items[], currency, value |
+| view_cart | Cart page viewed | items[], currency, value |
+| begin_checkout | Checkout started | items[], currency, value, coupon |
+| add_shipping_info | Shipping info entered | items[], currency, value, shipping_tier |
+| add_payment_info | Payment info entered | items[], currency, value, payment_type |
+| purchase | Purchase complete | transaction_id, items[], value, currency, tax, shipping, coupon |
+| refund | Refund processed | transaction_id, items[], value, currency |
+
+### 4. Lead Generation Events
+| Event | Trigger | Parameters |
+|-------|---------|-----------|
+| generate_lead | Lead form submitted | lead_type, form_name, value, currency |
+| form_start | User begins filling form | form_name |
+| form_submit | Form successfully submitted | form_name, form_id |
+| form_error | Form submission error | form_name, error_type |
+| demo_request | Demo requested | demo_type |
+| contact_form | Contact form submitted | subject, department |
+| newsletter_signup | Newsletter subscription | list_name |
+
+### 5. SaaS/Product Events
+| Event | Trigger | Parameters |
+|-------|---------|-----------|
+| trial_start | Free trial begins | plan_name |
+| feature_used | Core feature activated | feature_name, feature_category |
+| onboarding_step | Onboarding step completed | step_number, step_name |
+| onboarding_complete | Full onboarding done | time_to_complete |
+| plan_selected | Pricing plan chosen | plan_name, plan_price, billing_cycle |
+| upgrade | Plan upgraded | from_plan, to_plan, value |
+| downgrade | Plan downgraded | from_plan, to_plan |
+| churn | Subscription cancelled | reason, plan_name, lifetime_days |
+| invite_sent | User invited someone | invite_method |
+| invite_accepted | Invitee signed up | — |
+
+## Parameter Standards
+
+### Item Object (GA4 E-commerce)
+```json
+{
+  "item_id": "SKU_12345",
+  "item_name": "Product Name",
+  "affiliation": "Store Name",
+  "coupon": "SUMMER_2026",
+  "discount": 10.00,
+  "index": 0,
+  "item_brand": "Brand Name",
+  "item_category": "Category L1",
+  "item_category2": "Category L2",
+  "item_category3": "Category L3",
+  "item_list_id": "related_products",
+  "item_list_name": "Related Products",
+  "item_variant": "Blue / Large",
+  "price": 99.90,
+  "quantity": 1
+}
+```
+
+### Custom Dimensions (GA4)
+| Dimension | Scope | Example Values |
+|-----------|-------|---------------|
+| user_type | User | free, trial, paid, enterprise |
+| plan_name | User | basic, pro, enterprise |
+| account_age_days | User | 30, 90, 365 |
+| content_type | Event | blog, video, case_study |
+| experiment_id | Event | exp_pricing_v2 |
+| experiment_variant | Event | control, variant_a |
+
+### Custom Metrics (GA4)
+| Metric | Scope | Type | Example |
+|--------|-------|------|---------|
+| engagement_score | Event | Number | 0-100 |
+| lead_value | Event | Currency | 150.00 |
+| nps_score | Event | Number | -100 to 100 |
+
+## Data Layer Standards
+
+### Push Pattern
+```javascript
+// Always push, never mutate
+dataLayer.push({
+  event: 'event_name',
+  param_1: 'value_1',
+  param_2: 'value_2'
+});
+
+// For e-commerce, clear previous data
+dataLayer.push({ ecommerce: null });
+dataLayer.push({
+  event: 'purchase',
+  ecommerce: { /* ... */ }
+});
+```
+
+### Rules
+1. Never directly mutate `dataLayer` — always `.push()`
+2. Clear `ecommerce` object before each e-commerce push
+3. Never include PII (email, phone, name) in data layer
+4. Use consistent data types (string vs number)
+5. Include `event` key in every push
+6. Timestamp handled automatically by GTM
+
+## Validation Rules
+| Rule | Check |
+|------|-------|
+| Naming format | Matches `^[a-z][a-z0-9_]{2,39}$` |
+| Required params | event_name always present |
+| PII check | No email/phone/name patterns |
+| Value format | Numbers as numbers, not strings |
+| Currency format | ISO 4217 (BRL, USD, EUR) |
+| Item array | Non-empty for e-commerce events |

package/squad-growth/knowledge-base/attribution-models.md

@@ -0,0 +1,195 @@
+# Knowledge Base: Attribution Models
+
+## Attribution Model Comparison
+
+### Rule-Based Models
+| Model | Credit Distribution | Strengths | Weaknesses |
+|-------|-------------------|-----------|-----------|
+| Last Click | 100% to last touchpoint | Simple, easy to implement | Ignores discovery channels |
+| First Click | 100% to first touchpoint | Values awareness | Ignores conversion drivers |
+| Linear | Equal across all touchpoints | Fair distribution | No prioritization |
+| Time Decay | More to recent touchpoints | Values recency | May undervalue awareness |
+| Position-Based | 40% first, 40% last, 20% middle | Balanced | Arbitrary weights |
+
+### Algorithmic Models
+| Model | Approach | Requirements | Accuracy |
+|-------|---------|-------------|---------|
+| Data-Driven (GA4) | Google's ML algorithm | 300+ conversions/month | High |
+| Shapley Value | Game theory — marginal contribution | Moderate data | Very High |
+| Markov Chains | Transition probabilities | Large dataset | Very High |
+| Logistic Regression | Predictive modeling | Feature engineering | High |
+
+## Shapley Value Attribution
+
+### Concept
+Each channel's contribution = average marginal contribution across all possible coalitions.
+
+### Steps
+1. List all possible subsets (coalitions) of channels
+2. For each subset, calculate conversion probability
+3. For each channel, calculate marginal contribution to every subset
+4. Average marginal contributions = Shapley value
+
+### Example (3 channels: A, B, C)
+```
+Coalitions and conversion rates:
+  {} = 0%
+  {A} = 5%
+  {B} = 3%
+  {C} = 2%
+  {A,B} = 12%
+  {A,C} = 9%
+  {B,C} = 7%
+  {A,B,C} = 18%
+
+Channel A's marginal contributions:
+  {} → {A}: 5% - 0% = 5%
+  {B} → {A,B}: 12% - 3% = 9%
+  {C} → {A,C}: 9% - 2% = 7%
+  {B,C} → {A,B,C}: 18% - 7% = 11%
+
+Shapley(A) = average = (5 + 9 + 7 + 11) / 4 = 8%
+```
+
+## Markov Chain Attribution
+
+### Concept
+Model user journeys as state transitions. Attribution = removal effect (how many conversions lost if channel removed).
+
+### States
+- Start (entry point)
+- Channel states (each touchpoint)
+- Conversion (success)
+- Null (dropout)
+
+### Transition Matrix
+```
+From\To   | Start | Google | Meta | Email | Conv | Null
+----------|-------|--------|------|-------|------|-----
+Start     | 0     | 0.40   | 0.35 | 0.15  | 0    | 0.10
+Google    | 0     | 0.10   | 0.20 | 0.15  | 0.30 | 0.25
+Meta      | 0     | 0.25   | 0.05 | 0.20  | 0.20 | 0.30
+Email     | 0     | 0.10   | 0.10 | 0.05  | 0.50 | 0.25
+```
+
+### Removal Effect
+1. Remove channel X (set all transitions to Null)
+2. Recalculate total conversion probability
+3. Removal effect = Original CR - CR without X
+4. Attribution = Removal Effect(X) / Sum(All Removal Effects)
+
+## GA4 Attribution Settings
+
+### Configuration
+| Setting | Options | Recommended |
+|---------|---------|-------------|
+| Reporting attribution | Data-driven (default) | Data-driven |
+| Lookback window | 30/60/90 days | 90 days |
+| Acquisition conversion events | First user source | First user |
+| Other conversion events | Last click or data-driven | Data-driven |
+
+### GA4 Data-Driven Attribution
+- Uses Google's ML to analyze conversion paths
+- Requires 300+ conversions and 3,000+ ad interactions per month
+- Considers: path position, time between touchpoints, device, number of touchpoints
+- Falls back to last click if insufficient data
+
+## Cross-Device Attribution
+
+### Challenges
+| Challenge | Solution |
+|-----------|---------|
+| User on phone → converts on desktop | User ID matching (logged-in) |
+| Multiple devices, no login | Google Signals, probabilistic matching |
+| Privacy restrictions (iOS) | Server-side tracking, first-party data |
+| Walled gardens | Platform-specific attribution APIs |
+
+### User ID Implementation
+```javascript
+// GA4: Set user_id when user logs in
+gtag('set', { user_id: 'USER_12345' });
+
+// Also set as user property
+gtag('set', 'user_properties', {
+  user_id: 'USER_12345',
+  user_type: 'paid'
+});
+```
+
+## Incrementality Testing
+
+### Methods
+| Method | Description | Accuracy | Cost |
+|--------|-----------|---------|------|
+| Geo-based holdout | Stop ads in some regions, compare | High | Medium |
+| Ghost ads | Show control group a blank/PSA | Very High | High |
+| Budget on/off test | Turn channel on/off, measure impact | Medium | Medium |
+| Matched market test | Compare similar markets | High | Medium |
+
+### Incrementality Formula
+```
+Lift = (Test Group CR - Control Group CR) / Control Group CR × 100
+
+Incremental conversions = Total conversions × (1 - (Control CR / Test CR))
+
+iROAS = Incremental Revenue / Ad Spend
+```
+
+## Attribution Windows
+| Platform | Default Click | Default View | Customizable |
+|----------|-------------|-------------|-------------|
+| GA4 | 30 days | 1 day (engaged) | Yes (30/60/90) |
+| Google Ads | 30 days | 1 day | Yes |
+| Meta Ads | 7 days | 1 day | Yes (1/7/28 click, 1 view) |
+| LinkedIn | 30 days | 7 days | Yes |
+| TikTok | 7 days | 1 day | Yes |
+
+## Choosing the Right Model
+| Situation | Recommended Model |
+|-----------|------------------|
+| Low data volume (< 300 conv/mo) | Last click or position-based |
+| Medium volume (300-1000 conv/mo) | GA4 data-driven |
+| High volume (1000+ conv/mo) | Shapley or Markov |
+| B2B long sales cycle | Position-based or time decay |
+| B2C impulse purchase | Last click or data-driven |
+| Multi-channel campaigns | Data-driven or Shapley |
+| Single channel dominant | Last click is fine |
+
+## Multi-Touch Attribution Implementation
+
+### Model Selection Guide
+- **First-touch:** credits acquisition channel, best for top-of-funnel optimization
+- **Last-touch:** credits closing channel, best for bottom-of-funnel optimization
+- **Linear:** equal credit across all touchpoints, best for balanced view
+- **Time-decay:** more credit to recent touchpoints, best for short sales cycles
+- **Position-based (U-shaped):** 40% first, 40% last, 20% distributed middle
+- **Data-driven (GA4):** algorithmic, uses Shapley values
+
+## Platform-Specific Attribution
+
+### GA4
+- Data-driven attribution as default, cross-channel, 90-day lookback
+
+### Meta Attribution
+- 7-day click / 1-day view default, Meta Attribution API for server-side
+
+### Google Ads
+- Data-driven bidding, conversion modeling for privacy gaps
+
+## Incrementality Testing
+
+### Methods
+- **Geo-holdout:** split by geography, measure lift vs control
+- **PSA tests:** show non-branded ads to control group
+- **Ghost ads:** log would-have-shown impressions
+- **Conversion lift studies:** platform-native (Meta Lift, Google Experiments)
+
+## Decision Matrix
+
+| Scenario | Recommended Model |
+|----------|------------------|
+| Brand awareness campaigns | First-touch |
+| Performance/conversion campaigns | Last-touch or data-driven |
+| Multi-channel, long sales cycle | Position-based or data-driven |
+| Limited data (<300 conversions/month) | Position-based |
+| Sufficient data (300+ conversions) | Data-driven |

package/squad-growth/knowledge-base/cro-experimentation-framework.md

@@ -0,0 +1,208 @@
+# Knowledge Base: CRO Experimentation Framework
+
+## Experimentation Hierarchy
+
+### 1. Observation → Hypothesis → Experiment → Learning
+```
+DATA SOURCES:
+  Analytics → Heatmaps → Session Recordings → Surveys → User Tests
+      │
+      ▼
+INSIGHT:
+  "Users on mobile abandon cart at payment step (68% drop-off)"
+      │
+      ▼
+HYPOTHESIS:
+  "If we add Apple Pay to mobile checkout,
+   then conversion rate will increase by 15%,
+   because reducing payment friction addresses the #1 drop-off reason"
+      │
+      ▼
+EXPERIMENT:
+  A/B test: Control (current) vs Variant (Apple Pay added)
+  Sample: 5,000 users per variant, 14-day duration
+      │
+      ▼
+LEARNING:
+  Result + next hypothesis → Knowledge Base
+```
+
+## Hypothesis Framework
+
+### ICE Scoring
+```
+Score = Impact × Confidence × Ease (each 1-10)
+
+Impact:     How much will this move the metric? (1=minimal, 10=massive)
+Confidence: How sure are we this will work? (1=guess, 10=proven)
+Ease:       How easy is it to implement? (1=months, 10=hours)
+```
+
+### RICE Scoring (for larger teams)
+```
+Score = (Reach × Impact × Confidence) / Effort
+
+Reach:      Users affected per quarter
+Impact:     0.25 (minimal), 0.5 (low), 1 (medium), 2 (high), 3 (massive)
+Confidence: 100% (high), 80% (medium), 50% (low)
+Effort:     Person-weeks to implement
+```
+
+### Hypothesis Template
+```
+HYPOTHESIS #[ID]
+  Page/Flow: [where]
+  Observation: [what we see in data]
+  If we: [change we will make]
+  Then: [expected result + metric + magnitude]
+  Because: [psychological/behavioral reasoning]
+  ICE Score: I[_] × C[_] × E[_] = [total]
+  Primary Metric: [conversion rate, revenue, etc.]
+  Secondary Metrics: [engagement, bounce, etc.]
+  Guard Rails: [metrics that should NOT decrease]
+```
+
+## Statistical Foundations
+
+### Sample Size Calculation
+```
+n = (Z² × p × (1-p)) / E²
+
+Where:
+  Z = Z-score (1.96 for 95% confidence)
+  p = baseline conversion rate
+  E = minimum detectable effect (MDE)
+
+Practical formula:
+  n per variant = 16 × p × (1-p) / MDE²
+
+Example:
+  Baseline CR = 3% (p = 0.03)
+  MDE = 15% relative (0.45% absolute)
+  n = 16 × 0.03 × 0.97 / 0.0045² ≈ 22,963 per variant
+```
+
+### Statistical Significance
+| Concept | Threshold | Meaning |
+|---------|----------|---------|
+| Confidence level | 95% (α = 0.05) | 5% chance of false positive |
+| Statistical power | 80% (β = 0.20) | 20% chance of false negative |
+| p-value | < 0.05 | Reject null hypothesis |
+| MDE | 10-20% relative | Minimum meaningful change |
+
+### Common Pitfalls
+| Pitfall | Problem | Prevention |
+|---------|---------|-----------|
+| Peeking | Checking results too early | Pre-set duration, use sequential testing |
+| Multiple testing | Testing many variants inflates false positives | Bonferroni correction |
+| Simpson's Paradox | Aggregate hides segment-level effects | Always segment results |
+| Novelty effect | Users react to newness, not improvement | Run for 2+ weeks |
+| Selection bias | Non-random assignment | Use proper randomization |
+| Survivorship bias | Only analyzing completers | Intent-to-treat analysis |
+
+## Test Types
+
+### A/B Test
+- **What:** Two variants (control vs treatment)
+- **When:** Clear hypothesis, one variable change
+- **Duration:** Until statistical significance
+- **Traffic:** 50/50 split
+
+### A/B/n Test
+- **What:** Multiple variants (3-5 max)
+- **When:** Testing different approaches
+- **Caution:** Need more traffic (sample size per variant)
+
+### Multivariate Test (MVT)
+- **What:** Multiple elements changed simultaneously
+- **When:** Optimizing combinations (headline × image × CTA)
+- **Requirement:** Very high traffic volume
+
+### Split URL Test
+- **What:** Different pages/URLs entirely
+- **When:** Major redesigns, different flows
+- **Implementation:** Server-side redirect
+
+### Bandit Testing
+- **What:** Dynamically allocates more traffic to winning variant
+- **When:** Short campaigns, e-commerce promotions
+- **Trade-off:** Less statistical rigor, more revenue
+
+## CRO Audit Framework
+
+### Quantitative Analysis
+| Source | What to Look For |
+|--------|-----------------|
+| GA4 Funnel | Drop-off points per stage |
+| GA4 Path | Common user paths vs ideal path |
+| Heatmaps | Click distribution, scroll depth |
+| Session Recordings | Rage clicks, u-turns, confusion |
+| Form Analytics | Field-level abandonment |
+| Speed Metrics | LCP, INP correlation with conversion |
+
+### Qualitative Analysis
+| Method | What to Learn |
+|--------|-------------|
+| User surveys | Why did you not complete X? |
+| Exit surveys | What stopped you today? |
+| User tests | Task completion observation |
+| Customer interviews | Deep understanding of barriers |
+| Support tickets | Common complaints and confusion |
+| Review mining | Competitor reviews for friction insights |
+
+### Heuristic Evaluation (LIFT Model)
+| Factor | Question | Priority |
+|--------|---------|----------|
+| Value proposition | Is the value clear and compelling? | Highest |
+| Relevance | Does this match what brought the user here? | High |
+| Clarity | Is the message/action crystal clear? | High |
+| Urgency | Is there reason to act now? | Medium |
+| Anxiety | Are there trust/security concerns? | Medium |
+| Distraction | Are there competing actions/elements? | Medium |
+
+## Experiment Lifecycle
+
+### 1. Discovery (Week 1)
+- Review analytics data
+- Conduct heuristic evaluation
+- Prioritize opportunities
+
+### 2. Hypothesis (Week 2)
+- Write formal hypotheses
+- Score with ICE/RICE
+- Select top 2-3 for sprint
+
+### 3. Design (Week 2-3)
+- Create mockups/wireframes
+- Get stakeholder alignment
+- Technical feasibility check
+
+### 4. Implementation (Week 3-4)
+- Build variants in testing tool
+- QA across devices/browsers
+- Validate tracking
+
+### 5. Execution (Week 4-6+)
+- Launch experiment
+- Monitor for data quality issues
+- DO NOT peek at results
+
+### 6. Analysis (End of test)
+- Statistical significance check
+- Segment analysis
+- Revenue impact calculation
+
+### 7. Documentation (Post-test)
+- Record in experiment knowledge base
+- Share learnings
+- Generate next hypotheses
+
+## Tools Reference
+| Category | Tools |
+|----------|-------|
+| A/B Testing | Optimizely, VWO, Google Optimize (sunset), AB Tasty |
+| Heatmaps | Hotjar, FullStory, Microsoft Clarity (free) |
+| Surveys | Hotjar, Typeform, SurveyMonkey |
+| Analytics | GA4, Amplitude, Mixpanel |
+| Session Recording | FullStory, Hotjar, LogRocket |
+| Statistical | Evan Miller calculator, AB Test Guide, Statsig |

package/squad-growth/knowledge-base/data-visualization-guide.md

@@ -0,0 +1,140 @@
+# Knowledge Base: Data Visualization Guide
+
+## Chart Selection Matrix
+
+### By Data Relationship
+| Relationship | Best Chart | Alternatives |
+|-------------|-----------|-------------|
+| Trend over time | Line chart | Area chart, sparkline |
+| Comparison | Bar chart (horizontal) | Grouped bar, lollipop |
+| Part of whole | Stacked bar, treemap | Donut (max 5 slices), waffle |
+| Distribution | Histogram, box plot | Violin plot, density |
+| Correlation | Scatter plot | Bubble chart, heatmap |
+| Ranking | Horizontal bar (sorted) | Slope chart, bump chart |
+| Flow/Process | Sankey, funnel | Waterfall chart |
+| Geographic | Choropleth map | Bubble map, hex map |
+| KPI status | Scorecard, gauge | Bullet chart, traffic light |
+
+### By Business Context
+| Context | Chart | Why |
+|---------|-------|-----|
+| Revenue trend | Line chart (dual axis: revenue + growth%) | Shows trajectory and acceleration |
+| Channel comparison | Horizontal bar (sorted by value) | Easy ranking comparison |
+| Funnel analysis | Funnel chart | Intuitive drop-off visualization |
+| Budget allocation | Treemap | Shows proportions at a glance |
+| Campaign ROAS | Scatter (X: spend, Y: ROAS, size: revenue) | Efficiency + scale in one view |
+| Cohort retention | Heatmap (triangle) | Classic cohort visualization |
+| KPI dashboard | Scorecards + sparklines | Executive overview |
+
+## Design Principles
+
+### 1. Data-Ink Ratio (Edward Tufte)
+- Maximize data-ink, minimize non-data-ink
+- Remove chartjunk: 3D effects, unnecessary gridlines, decorative elements
+- Every pixel should convey information
+
+### 2. Pre-Attentive Attributes
+| Attribute | Use For | Example |
+|-----------|--------|---------|
+| Color hue | Categories | Channel = blue/red/green |
+| Color intensity | Magnitude | Darker = higher value |
+| Size | Quantity | Bigger bubble = more revenue |
+| Position | Precise values | X/Y axis placement |
+| Length | Comparison | Bar length = value |
+| Orientation | Direction | Arrow up/down for trend |
+
+### 3. Color Usage
+| Rule | Guideline |
+|------|----------|
+| Sequential | One hue, varying intensity (for magnitude) |
+| Diverging | Two hues from center (for above/below target) |
+| Categorical | Distinct hues (max 7 categories) |
+| Semantic | Green=good, Red=bad, Yellow=warning |
+| Accessibility | Use colorblind-safe palettes (avoid red-green only) |
+| Highlight | Use color to draw attention to key insight |
+
+**Recommended palettes:**
+- Sequential: Blues (`#EBF5FB` → `#1B4F72`)
+- Diverging: Red-Blue (`#E74C3C` → `#3498DB`)
+- Categorical: Tableau 10, ColorBrewer Set2
+
+### 4. Typography in Charts
+| Element | Size | Weight |
+|---------|------|--------|
+| Chart title | 16-18px | Bold |
+| Subtitle/annotation | 12-14px | Regular |
+| Axis labels | 11-12px | Regular |
+| Data labels | 10-11px | Regular |
+| Source/footnote | 9-10px | Light |
+
+## Dashboard Design Patterns
+
+### Layout Principles
+1. **Z-pattern reading** — Most important KPI top-left
+2. **Progressive disclosure** — Overview first, details on demand
+3. **Consistent grid** — 12-column grid for alignment
+4. **White space** — Don't overcrowd; breathing room improves comprehension
+5. **Context always** — Every number needs comparison (target, prior period, trend)
+
+### KPI Card Anatomy
+```
+┌─────────────────────────┐
+│ Metric Name        [i]  │
+│                         │
+│    R$ 142.5K            │  ← Primary value (large)
+│    ▲ 12.3% vs last mo  │  ← Comparison (colored)
+│    Target: R$150K       │  ← Context
+│    ▂▃▅▆▇▆▅▇ (sparkline) │  ← Trend
+└─────────────────────────┘
+```
+
+### Dashboard Hierarchy
+| Level | Content | Interaction |
+|-------|---------|-------------|
+| L1 Summary | 4-6 KPI cards + 1-2 charts | View only |
+| L2 Analysis | Detailed charts by dimension | Filter, date range |
+| L3 Exploration | Data tables, custom queries | Sort, search, export |
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| Pie chart with 10+ slices | Unreadable | Use horizontal bar |
+| Dual y-axis (misleading) | Implies correlation | Two separate charts |
+| Truncated y-axis | Exaggerates differences | Start at zero (bars) |
+| 3D charts | Distorts perception | Always use 2D |
+| Rainbow color scheme | No meaning, inaccessible | Semantic or sequential colors |
+| Too many metrics | Decision paralysis | Max 6-8 per dashboard view |
+| Numbers without context | Meaningless in isolation | Add target, trend, comparison |
+| Animated transitions | Distraction | Use only for state changes |
+
+## Annotation Best Practices
+| When to Annotate | Example |
+|-----------------|---------|
+| Anomalies | "Black Friday spike — 3x normal traffic" |
+| Launches | "New feature launched Nov 15" |
+| External events | "Competitor shutdown — traffic surge" |
+| Methodology changes | "Attribution model changed to data-driven" |
+| Targets | Horizontal reference line at target value |
+
+## Tools Reference
+| Tool | Type | Best For |
+|------|------|---------|
+| Looker Studio | Cloud BI | GA4 dashboards (free) |
+| Metabase | Self-hosted BI | SQL-based dashboards |
+| Preset (Superset) | Cloud BI | Data team dashboards |
+| Grafana | Monitoring | Real-time metrics |
+| Figma | Design | Dashboard mockups |
+| D3.js | Code | Custom visualizations |
+| Chart.js | Code | Simple web charts |
+| Observable | Notebooks | Exploratory analysis |
+
+## Storytelling with Data (Cole Nussbaumer Knaflic)
+
+### 6 Steps
+1. **Understand the context** — Who, what, how
+2. **Choose the right visual** — Chart selection matrix
+3. **Eliminate clutter** — Remove non-data elements
+4. **Focus attention** — Use pre-attentive attributes
+5. **Think like a designer** — Form follows function
+6. **Tell a story** — Setup → Conflict → Resolution