hive-skills 0.1.0

package/assets/skills/authored/data-analysis/composable/BUNDLE.md

@@ -0,0 +1,186 @@
+<!-- GENERATED by tools/hive.py compile. Do not hand-edit. -->
+# data-analysis: Compiled Skill Bundle (v1.0.0)
+
+All composable mini-skills for `data-analysis` concatenated in index order, frontmatter stripped. Regenerate with `tools/hive.py compile <skill-dir>`. Do not edit by hand.
+
+---
+<!-- module: 01-data-quality-profiling.md -->
+
+# Data Quality Profiling & Cleaning Decisions
+
+Never compute a headline number before profiling the data. Rushing to a total on dirty data produces confident, wrong answers.
+
+**Profiling checklist for every dataset:**
+- **Shape and grain.** How many rows, and what does one row represent? "One row = one order line" vs "one row = one order" changes every aggregation. State the grain explicitly.
+- **Row count vs. expected.** Does the count match what the business expects for the period? A month with 3x normal rows signals duplication or a double-loaded file.
+- **Nulls per column.** Count and locate missing values. Revenue 8% null is a different problem from 0.1% null.
+- **Ranges and distributions.** Min/max/quartiles for numerics. Negative prices, zero quantities, future dates, or a max 1000x the median flag problems.
+- **Uniqueness.** Are IDs that should be unique actually unique? Duplicate order IDs are the classic silent inflator.
+- **Categoricals.** How many distinct values? Look for the same thing spelled differently ("US", "USA", "United States"), stray whitespace, and case differences.
+
+**Cleaning decisions must be explicit and defensible.** For each issue decide and record: drop, impute, cap, or keep-and-flag, and why.
+- Missing revenue on 0.1% of rows: dropping is usually fine; note it.
+- Missing region on 15% of rows: dropping biases the geography analysis. Keep as "Unknown" and report its size.
+- One $2,000,000 transaction when the median is $200: investigate before deciding. It may be real (an enterprise deal) or an error (cents entered as dollars). **Never silently delete it.**
+
+**Rule: every cleaning choice changes the answer, so every cleaning choice must be stated.** An analysis whose data decisions are hidden cannot be trusted or reproduced.
+
+**Worked example.** You receive 50,000 sales rows. Profiling shows 51,200 order IDs but only 50,000 distinct (1,200 duplicates that would inflate any revenue sum). Region is null on 12% of rows. Two orders are dated in 2027. Actions: dedupe on order ID (document the key), keep null region as "Unknown (12%)", quarantine the future-dated rows pending a source check. Record all three decisions before computing a single total.
+
+---
+<!-- module: 02-aggregation-pitfalls.md -->
+
+# Aggregation Correctness Pitfalls
+
+Most analytical errors are not math errors: they are aggregation errors on messy data.
+
+- **Duplicates inflate sums and counts.** Before `SUM(revenue)`, confirm the grain and deduplicate on the true key. A joined table that fans out (one order joined to many line items) multiplies the order's revenue by its line count. Check: does `SUM` at this grain match `SUM` at the source grain?
+- **Averages hide distributions and are wrecked by outliers.** The mean is the wrong summary for skewed data: revenue, session length, and deal size are almost always right-skewed. Report the **median** alongside the mean; if mean ≫ median, say so and lead with median. "Average order value $850" can be one whale plus a hundred $40 orders.
+- **Beware averaging averages.** The average of per-customer average order values is *not* the overall average order value. Aggregate from the base rows, or use a properly weighted average.
+- **Missing values distort denominators.** `AVG` skips nulls; `COUNT(*)` includes them; `COUNT(col)` does not. Decide whether a null means zero (impute 0) or unknown (exclude); they give different results. "Signups / visits" is wrong if some visits are null.
+- **Simpson's paradox.** A trend in the aggregate can reverse within every segment. If overall conversion rose but fell in each channel, a mix shift is responsible: always sanity-check aggregate movements against segment movements.
+- **Count distinct vs. count.** "1,000 orders" and "1,000 customers" differ when customers repeat. Use `COUNT(DISTINCT customer_id)` for customers.
+
+**Worked example.** A table joins `orders` to `payments`; some orders have 2 payment rows. `SUM(order_total)` now double-counts those orders. Fix: aggregate `order_total` at the order grain first, then join to payments. Note that `SUM(DISTINCT order_total)` is *not* a fix: two genuinely equal order totals would be wrongly collapsed. Deduplicate rows on the real key, don't dedupe values.
+
+The habit that prevents most of these: before every aggregate, state the grain out loud, confirm the key is unique at that grain, and check whether the metric is skewed enough that the mean will mislead.
+
+---
+<!-- module: 03-time-series.md -->
+
+# Time-Series Analysis
+
+- **Growth rates.** Period-over-period growth = (current − prior) / prior. Always state the base and pair a percentage with absolute numbers. A "200% increase" from 1 to 3 is trivially small in absolute terms.
+- **Partial periods are the number-one time-series trap.** If the current month is only 40% elapsed, its total is not comparable to full prior months and will look like a crash. Either exclude the partial period, run-rate it with a clear caveat, or compare like-for-like (month-to-date vs. same-day-of-month prior). Always label partial periods.
+- **Seasonality.** Compare year-over-year, not just month-over-month, when the business is seasonal. December vs. November tells you little if December always spikes; December vs. last December does.
+- **Choose the right growth summary.** For multi-period growth use CAGR, defined as (end/start)^(1/periods) − 1, not the average of per-period growth rates, which overstates. Averaging +50% then −50% gives 0%, but the true result is −25%.
+- **Smoothing.** Use trailing moving averages (e.g., 7-day) to reveal trend through noise, but note that smoothing lags turning points.
+- **Watch the denominator over time.** A rising total can come from more customers, not more per customer: decompose growth into volume × rate whenever possible.
+
+**Worked example.** Revenue "dropped 60% this month." The month is 12 days in. Run-rate: $400k in 12 days → ~$1.0M projected vs. $950k last month (actually up). Report the run-rate *with* the caveat that it's a projection; never present the raw partial total as if it were final. Reporting the −60% would trigger a false alarm.
+
+**Second example.** A dashboard shows month-over-month revenue down every December-to-January. That is seasonality, not decline: the correct comparison is January vs. prior January. Presenting the MoM drop as a trend would be misleading.
+
+The discipline: for any time comparison, verify the two periods are truly comparable (same length, same completeness, same season) before computing or reporting a change.
+
+---
+<!-- module: 04-segmentation.md -->
+
+# Segmentation
+
+Segmentation turns a flat number into an insight by asking "for whom / where / which?"
+
+- Segment by the dimensions that drive decisions: customer type, region, product, channel, cohort, plan tier.
+- **Always show segment size alongside segment metric.** A segment with 300% growth on 4 customers is noise; the same growth on 4,000 customers is a strategy. Report both the rate and the base count/volume.
+- **Beware small segments.** Percentages on small n are volatile: set a minimum sample threshold and flag or suppress segments below it.
+- Look for **concentration**: often a small fraction of customers or products drives most revenue (Pareto). Compute the share of the top decile; concentration risk is itself a finding.
+- **Cohorts** (grouping by join/acquisition period) separate "are new users better?" from "is the whole base aging?", which is critical for retention and LTV questions.
+- **Contribution to change.** When a total moves, decompose *which segments* caused it. "Revenue up $200k" is far more useful as "Enterprise +$260k, SMB −$60k."
+
+**Worked example.** Overall revenue is flat month-over-month, seemingly a non-event. Segmenting reveals Enterprise +$260k and SMB −$260k. The flat aggregate hid a major mix shift and an SMB problem worth acting on. The segmentation *is* the insight; the aggregate concealed it.
+
+**Second example.** A "region with 300% growth" turns out to have 3 customers, up from 1. Flag it as too small to act on rather than headline it. Meanwhile a mature region growing 8% on 5,000 customers is the real story. Size context flips which finding matters.
+
+**Concentration example.** If the top 10% of customers drive 70% of revenue, that concentration is a finding in itself: it signals both an upsell base and a churn risk if a few accounts leave. Report the concentration ratio explicitly.
+
+The discipline: never report a segment percentage without its denominator, and always test whether a flat or moving aggregate is masking offsetting segment movements.
+
+---
+<!-- module: 05-discount-pricing.md -->
+
+# Discount, Pricing & Margin Analysis
+
+- **Discount depth vs. discount penetration are different metrics.** Depth = average discount % on discounted orders. Penetration = share of orders that get any discount. Report both. A low average discount can hide that 80% of orders receive *some* discount: high penetration, low depth is a different problem from low penetration, high depth.
+- **Evaluate discounts on margin, not revenue.** A 20% discount on a 30%-margin product does not cut profit by 20%: it can erase most of the margin. A $100 item at 30% margin earns $30; a 20% discount drops price to $80, and if cost stays $70, margin falls to $10 (a 67% margin cut from a 20% discount). Always tie discounting back to unit economics.
+- **Use net/effective price.** Compute realized price after all discounts, credits, and refunds (not list price) as the basis for any pricing conclusion. Watch for discount stacking (multiple discounts compounding).
+- **Confounding with volume.** "Discounted orders are bigger" may mean discounts drive volume, or that big orders negotiate discounts. Correlation is not causation; state which direction the data can and cannot support.
+- **Elasticity claims need controlled comparison**, not a raw before/after that ignores seasonality and product mix. Be explicit about what a discount analysis can and cannot prove.
+
+**Worked example.** SMB orders show a 20% average discount and revenue looks healthy, so discounting seems fine. But margin analysis shows SMB products average 30% margin, so the 20% discount cuts unit profit roughly in half. Penetration is 80%: nearly every SMB order is discounted. The finding is not "discounts are moderate" but "discounting is quietly destroying SMB margin," which points to a specific action (cap discount depth or reduce penetration).
+
+The discipline: never conclude a discount is "small" or "fine" from the revenue view alone. Always translate it to margin impact and check both depth and penetration before making a pricing recommendation.
+
+---
+<!-- module: 06-insight-generation.md -->
+
+# Generating Insight Beyond Aggregates
+
+A table of totals is not analysis. Insight answers "so what?" Push every number one level further.
+
+Four moves that turn a number into a finding:
+- **Compare**: vs. prior period, vs. target, vs. benchmark, vs. other segments. A number alone ("revenue was $2M") means nothing without a reference point. Is $2M good? Only a comparison tells you.
+- **Decompose**: break a change into its drivers: price × volume, new × existing customers, which segments moved. "Revenue up $200k" becomes "driven entirely by Enterprise upsell; SMB actually shrank."
+- **Explain**: offer the most likely cause and note what would confirm or refute it. Distinguish observation from hypothesis.
+- **Quantify impact**: translate to money, users, or risk, and to the decision at stake. "This costs ~$120k/quarter in margin" lands; "discounts are high" doesn't.
+
+Then **surface the surprising**: the outlier, the reversal, the concentration, the thing that contradicts the assumption. That is where the value lives. A finding that confirms what everyone already believed rarely changes a decision.
+
+**Test for every finding:** ask "so what should we do differently?" If a number implies no decision, it may be context, not a finding: demote it to background.
+
+**Worked example.** Draft says: "Q3 revenue was $2.0M. North America was $1.2M. Enterprise was $1.4M." That is three facts, no insight. Pushed further: "Q3 revenue grew 12% ($1.8M → $2.0M), but *all* net growth came from Enterprise (+$260k); SMB declined $60k for the second straight quarter (the first sign the SMB motion is stalling and worth investigating before Q4 planning)." Same underlying numbers, but now there is a comparison, a decomposition, a likely story, and a decision implication.
+
+**Second example.** "Average order value is $850" is a bare aggregate. Insight: "AOV is $850, but the median is $210 (a handful of enterprise deals pull the mean up 4x). For SMB-focused decisions, use the median; the $850 figure will mislead capacity and pricing planning." The move here is recognizing the distribution and stating the consequence for a decision.
+
+The discipline: never ship a bare number. Attach a comparison and a "so what" to every figure that reaches the reader.
+
+---
+<!-- module: 07-executive-writing.md -->
+
+# Writing for Executive Audiences
+
+Executives read for decisions, not for your method. Structure and language should serve a busy reader who will act on three sentences.
+
+- **Lead with the answer (BLUF: bottom line up front).** The headline finding and its implication come first; supporting detail follows. Never make a reader wade through methodology to reach the conclusion. If they read only the first line, they should get the point.
+- **Quantify and contextualize.** "Revenue grew 12% ($1.8M → $2.0M), driven mostly by Enterprise," not "revenue grew." Every claim carries a number and a reference point.
+- **Three-to-five findings, ranked by impact.** A report with 20 equal bullets has no priorities. Lead with what matters most; cut or appendix the rest.
+- **Round appropriately.** Say "$2.0M," not "$2,013,847.22." Spurious precision signals poor judgment and slows the reader. Match precision to the decision.
+- **Translate to the business.** Tie every metric to revenue, cost, risk, or growth. Replace jargon and raw metric names with plain business language: "customers who stopped using us" beats "MAU churn delta."
+- **Visual discipline.** One chart, one message; label it with the takeaway ("Enterprise now 70% of revenue"), not just "Figure 3." If a chart needs a paragraph to interpret, it's the wrong chart.
+
+**Worked example (before/after opening):**
+- Before: "We queried the transactions table for Q3, deduplicated on order ID, excluded refunds, and after grouping by segment we observed the following distribution of revenue..."
+- After: "**Q3 revenue hit $2.0M (+12%), but growth is now entirely Enterprise: SMB shrank for the second quarter.** Details below." The method belongs in an appendix or a footnote, not the lead.
+
+**Second example (precision and translation):**
+- Before: "Net revenue retention was 1.1372 for the enterprise cohort."
+- After: "Enterprise customers grew ~14% in spend without any new logos: existing accounts are expanding, which de-risks the Q4 number."
+
+The discipline: write the one sentence you'd want the CEO to repeat in a meeting, put it first, and make everything else support it.
+
+---
+<!-- module: 08-recommendations.md -->
+
+# Recommendations & Framing
+
+A recommendation is where analysis becomes value, and where analysts most often overreach or under-deliver.
+
+- **Recommendations must follow from the data shown**, not appear from nowhere. Each should trace to a specific finding in the report. If a reader can't point to the number behind a recommendation, it's an opinion, not analysis.
+- **Be specific and actionable.** "Cap SMB discounts at 15%, projected to recover ~$120k in annual margin," not "improve discounting." A good recommendation names the action, the target, and the expected impact.
+- **Acknowledge uncertainty and tradeoffs.** State your confidence and what could change the conclusion. Overclaiming from correlation destroys credibility faster than admitting a limit. "This assumes discount elasticity is low, which we haven't tested" is a strength, not a weakness.
+- **Prioritize by impact and effort.** Rank recommendations; don't hand over a flat list of ten. Lead with high-impact, low-effort moves.
+- **Separate what the data says from what you infer.** "Discounted orders are 2x larger (observed)" is a fact; "so discounts likely drive larger orders (hypothesis, needs a controlled test)" is an inference. Label each. Conflating them is how correlation gets sold as causation.
+
+**Worked example.** Finding: SMB discount penetration is 80% at 20% average depth, and SMB margin is ~30%, so discounting roughly halves SMB unit profit. Recommendation: "Pilot a 15% discount cap on SMB for one quarter in two regions; projected to recover ~$120k annualized margin if volume holds. Risk: if SMB volume is discount-elastic, we may lose orders; the pilot's control regions will measure this. Confidence: medium; we have the margin math but not the elasticity." Notice it traces to the finding, quantifies impact, names the risk, states confidence, and proposes a test rather than a blanket rollout.
+
+**Counter-example to avoid:** "Discounts are hurting us, so stop discounting." No target, no quantified impact, ignores that discounts may drive volume, and overclaims causation. It would likely be wrong and would erode trust in the whole report.
+
+The discipline: for every recommendation, be able to say which finding it rests on, what it's worth, how confident you are, and what would prove it wrong.
+
+---
+<!-- module: 09-reproducibility-assumptions.md -->
+
+# Reproducibility & Stating Assumptions
+
+An analysis nobody can reproduce or trust is worthless, however clever the method.
+
+- **State every assumption**: date range, filters applied, how nulls/outliers/duplicates were handled, currency, timezone, and the definition of each metric ("active" = ?). Assumptions left unstated silently make numbers non-comparable across reports and people.
+- **Define metrics precisely.** "Revenue": gross or net of refunds? Booked or recognized? Including tax or not? Two analysts with different definitions produce different totals and both look correct. Pin the definition down and write it near the number.
+- **Make it re-runnable.** Deterministic steps, a fixed seed for any sampling, and the data source plus snapshot date recorded. Someone else running your steps on the same data must get the same numbers. If a rerun tomorrow gives a different answer, say why (live data) and pin a snapshot.
+- **Show denominators and sample sizes** so a reader can judge reliability. "12% conversion" means little without knowing it's 12 of 100 vs. 12,000 of 100,000.
+- **Sanity-check before publishing.** Do totals reconcile to a known source (e.g., does your revenue sum match finance's)? Do the parts sum to the whole? Does the number pass a smell test against prior periods? Reconciliation catches the duplicated-join and wrong-filter errors that pass silently otherwise.
+
+**Worked example.** A report states "Q3 revenue: $2.0M." Reproducible version: "Q3 revenue (net of refunds, recognized, USD): $2.03M. Source: `transactions` snapshot 2026-10-02, deduplicated on order_id (1,200 dupes removed), refunds excluded (−$140k), 12% of rows had null region and are grouped as 'Unknown'. Reconciles to finance's GL within 0.5%." A reader can now trust it, reproduce it, and compare it to next quarter on the same basis.
+
+**Why it matters.** The difference between trustworthy reporting and a plausible-looking guess is not cleverness: it's that the trustworthy one states its assumptions, defines its metrics, reconciles to a known truth, and can be re-run to the same result. When two reports disagree, the one that documented its basis wins the argument.
+
+The discipline: before publishing, write down the date range, filters, null/outlier/duplicate handling, and metric definitions, then reconcile the headline number against an independent source.

package/assets/skills/authored/data-analysis/composable/INDEX.md

@@ -0,0 +1,13 @@
+# Tabular Data Analysis & Reporting: Composable Index
+
+Loading policy: read this menu, then load 00-core (if present) plus the minis relevant to your task. If most of this skill is relevant, load BUNDLE.md (or a matching presets/*.md) in one read instead.
+
+- **01-data-quality-profiling.md** - Profile data and make explicit cleaning decisions. *Load when* first receiving any dataset, before computing anything.
+- **02-aggregation-pitfalls.md** - Duplicates, mean vs median, missing-value denominators, Simpson's paradox. *Load when* summing, averaging, counting, or joining.
+- **03-time-series.md** - Growth rates, partial periods, seasonality, CAGR, smoothing. *Load when* analyzing anything over time.
+- **04-segmentation.md** - Slicing by dimension, segment size, cohorts, concentration. *Load when* breaking a metric down by group.
+- **05-discount-pricing.md** - Depth vs penetration, margin impact, net price, confounders. *Load when* analyzing discounts, pricing, or margin.
+- **06-insight-generation.md** - Moving from totals to "so what": compare, decompose, explain, quantify. *Load when* a draft is just a table of numbers.
+- **07-executive-writing.md** - BLUF, ranking findings, rounding, business translation. *Load when* writing up results for leadership.
+- **08-recommendations.md** - Framing actionable, data-traceable recommendations with uncertainty. *Load when* proposing actions.
+- **09-reproducibility-assumptions.md** - Stating assumptions, defining metrics, reconciling. *Load when* finalizing any analysis.

package/assets/skills/authored/data-analysis/composable/VERSION

@@ -0,0 +1 @@
+1.0.0

package/assets/skills/authored/data-analysis/composable/mini/01-data-quality-profiling.md

@@ -0,0 +1,26 @@
+---
+pairs-with:
+  - 02-aggregation-pitfalls.md
+  - 09-reproducibility-assumptions.md
+---
+
+# Data Quality Profiling & Cleaning Decisions
+
+Never compute a headline number before profiling the data. Rushing to a total on dirty data produces confident, wrong answers.
+
+**Profiling checklist for every dataset:**
+- **Shape and grain.** How many rows, and what does one row represent? "One row = one order line" vs "one row = one order" changes every aggregation. State the grain explicitly.
+- **Row count vs. expected.** Does the count match what the business expects for the period? A month with 3x normal rows signals duplication or a double-loaded file.
+- **Nulls per column.** Count and locate missing values. Revenue 8% null is a different problem from 0.1% null.
+- **Ranges and distributions.** Min/max/quartiles for numerics. Negative prices, zero quantities, future dates, or a max 1000x the median flag problems.
+- **Uniqueness.** Are IDs that should be unique actually unique? Duplicate order IDs are the classic silent inflator.
+- **Categoricals.** How many distinct values? Look for the same thing spelled differently ("US", "USA", "United States"), stray whitespace, and case differences.
+
+**Cleaning decisions must be explicit and defensible.** For each issue decide and record: drop, impute, cap, or keep-and-flag, and why.
+- Missing revenue on 0.1% of rows: dropping is usually fine; note it.
+- Missing region on 15% of rows: dropping biases the geography analysis. Keep as "Unknown" and report its size.
+- One $2,000,000 transaction when the median is $200: investigate before deciding. It may be real (an enterprise deal) or an error (cents entered as dollars). **Never silently delete it.**
+
+**Rule: every cleaning choice changes the answer, so every cleaning choice must be stated.** An analysis whose data decisions are hidden cannot be trusted or reproduced.
+
+**Worked example.** You receive 50,000 sales rows. Profiling shows 51,200 order IDs but only 50,000 distinct (1,200 duplicates that would inflate any revenue sum). Region is null on 12% of rows. Two orders are dated in 2027. Actions: dedupe on order ID (document the key), keep null region as "Unknown (12%)", quarantine the future-dated rows pending a source check. Record all three decisions before computing a single total.

package/assets/skills/authored/data-analysis/composable/mini/02-aggregation-pitfalls.md

@@ -0,0 +1,21 @@
+---
+requires:
+  - 01-data-quality-profiling.md
+pairs-with:
+  - 04-segmentation.md
+---
+
+# Aggregation Correctness Pitfalls
+
+Most analytical errors are not math errors: they are aggregation errors on messy data.
+
+- **Duplicates inflate sums and counts.** Before `SUM(revenue)`, confirm the grain and deduplicate on the true key. A joined table that fans out (one order joined to many line items) multiplies the order's revenue by its line count. Check: does `SUM` at this grain match `SUM` at the source grain?
+- **Averages hide distributions and are wrecked by outliers.** The mean is the wrong summary for skewed data: revenue, session length, and deal size are almost always right-skewed. Report the **median** alongside the mean; if mean ≫ median, say so and lead with median. "Average order value $850" can be one whale plus a hundred $40 orders.
+- **Beware averaging averages.** The average of per-customer average order values is *not* the overall average order value. Aggregate from the base rows, or use a properly weighted average.
+- **Missing values distort denominators.** `AVG` skips nulls; `COUNT(*)` includes them; `COUNT(col)` does not. Decide whether a null means zero (impute 0) or unknown (exclude); they give different results. "Signups / visits" is wrong if some visits are null.
+- **Simpson's paradox.** A trend in the aggregate can reverse within every segment. If overall conversion rose but fell in each channel, a mix shift is responsible: always sanity-check aggregate movements against segment movements.
+- **Count distinct vs. count.** "1,000 orders" and "1,000 customers" differ when customers repeat. Use `COUNT(DISTINCT customer_id)` for customers.
+
+**Worked example.** A table joins `orders` to `payments`; some orders have 2 payment rows. `SUM(order_total)` now double-counts those orders. Fix: aggregate `order_total` at the order grain first, then join to payments. Note that `SUM(DISTINCT order_total)` is *not* a fix: two genuinely equal order totals would be wrongly collapsed. Deduplicate rows on the real key, don't dedupe values.
+
+The habit that prevents most of these: before every aggregate, state the grain out loud, confirm the key is unique at that grain, and check whether the metric is skewed enough that the mean will mislead.

package/assets/skills/authored/data-analysis/composable/mini/03-time-series.md

@@ -0,0 +1,19 @@
+---
+pairs-with:
+  - 02-aggregation-pitfalls.md
+---
+
+# Time-Series Analysis
+
+- **Growth rates.** Period-over-period growth = (current − prior) / prior. Always state the base and pair a percentage with absolute numbers. A "200% increase" from 1 to 3 is trivially small in absolute terms.
+- **Partial periods are the number-one time-series trap.** If the current month is only 40% elapsed, its total is not comparable to full prior months and will look like a crash. Either exclude the partial period, run-rate it with a clear caveat, or compare like-for-like (month-to-date vs. same-day-of-month prior). Always label partial periods.
+- **Seasonality.** Compare year-over-year, not just month-over-month, when the business is seasonal. December vs. November tells you little if December always spikes; December vs. last December does.
+- **Choose the right growth summary.** For multi-period growth use CAGR, defined as (end/start)^(1/periods) − 1, not the average of per-period growth rates, which overstates. Averaging +50% then −50% gives 0%, but the true result is −25%.
+- **Smoothing.** Use trailing moving averages (e.g., 7-day) to reveal trend through noise, but note that smoothing lags turning points.
+- **Watch the denominator over time.** A rising total can come from more customers, not more per customer: decompose growth into volume × rate whenever possible.
+
+**Worked example.** Revenue "dropped 60% this month." The month is 12 days in. Run-rate: $400k in 12 days → ~$1.0M projected vs. $950k last month (actually up). Report the run-rate *with* the caveat that it's a projection; never present the raw partial total as if it were final. Reporting the −60% would trigger a false alarm.
+
+**Second example.** A dashboard shows month-over-month revenue down every December-to-January. That is seasonality, not decline: the correct comparison is January vs. prior January. Presenting the MoM drop as a trend would be misleading.
+
+The discipline: for any time comparison, verify the two periods are truly comparable (same length, same completeness, same season) before computing or reporting a change.

package/assets/skills/authored/data-analysis/composable/mini/04-segmentation.md

@@ -0,0 +1,23 @@
+---
+pairs-with:
+  - 06-insight-generation.md
+---
+
+# Segmentation
+
+Segmentation turns a flat number into an insight by asking "for whom / where / which?"
+
+- Segment by the dimensions that drive decisions: customer type, region, product, channel, cohort, plan tier.
+- **Always show segment size alongside segment metric.** A segment with 300% growth on 4 customers is noise; the same growth on 4,000 customers is a strategy. Report both the rate and the base count/volume.
+- **Beware small segments.** Percentages on small n are volatile: set a minimum sample threshold and flag or suppress segments below it.
+- Look for **concentration**: often a small fraction of customers or products drives most revenue (Pareto). Compute the share of the top decile; concentration risk is itself a finding.
+- **Cohorts** (grouping by join/acquisition period) separate "are new users better?" from "is the whole base aging?", which is critical for retention and LTV questions.
+- **Contribution to change.** When a total moves, decompose *which segments* caused it. "Revenue up $200k" is far more useful as "Enterprise +$260k, SMB −$60k."
+
+**Worked example.** Overall revenue is flat month-over-month, seemingly a non-event. Segmenting reveals Enterprise +$260k and SMB −$260k. The flat aggregate hid a major mix shift and an SMB problem worth acting on. The segmentation *is* the insight; the aggregate concealed it.
+
+**Second example.** A "region with 300% growth" turns out to have 3 customers, up from 1. Flag it as too small to act on rather than headline it. Meanwhile a mature region growing 8% on 5,000 customers is the real story. Size context flips which finding matters.
+
+**Concentration example.** If the top 10% of customers drive 70% of revenue, that concentration is a finding in itself: it signals both an upsell base and a churn risk if a few accounts leave. Report the concentration ratio explicitly.
+
+The discipline: never report a segment percentage without its denominator, and always test whether a flat or moving aggregate is masking offsetting segment movements.

package/assets/skills/authored/data-analysis/composable/mini/05-discount-pricing.md

@@ -0,0 +1,17 @@
+---
+pairs-with:
+  - 06-insight-generation.md
+  - 08-recommendations.md
+---
+
+# Discount, Pricing & Margin Analysis
+
+- **Discount depth vs. discount penetration are different metrics.** Depth = average discount % on discounted orders. Penetration = share of orders that get any discount. Report both. A low average discount can hide that 80% of orders receive *some* discount: high penetration, low depth is a different problem from low penetration, high depth.
+- **Evaluate discounts on margin, not revenue.** A 20% discount on a 30%-margin product does not cut profit by 20%: it can erase most of the margin. A $100 item at 30% margin earns $30; a 20% discount drops price to $80, and if cost stays $70, margin falls to $10 (a 67% margin cut from a 20% discount). Always tie discounting back to unit economics.
+- **Use net/effective price.** Compute realized price after all discounts, credits, and refunds (not list price) as the basis for any pricing conclusion. Watch for discount stacking (multiple discounts compounding).
+- **Confounding with volume.** "Discounted orders are bigger" may mean discounts drive volume, or that big orders negotiate discounts. Correlation is not causation; state which direction the data can and cannot support.
+- **Elasticity claims need controlled comparison**, not a raw before/after that ignores seasonality and product mix. Be explicit about what a discount analysis can and cannot prove.
+
+**Worked example.** SMB orders show a 20% average discount and revenue looks healthy, so discounting seems fine. But margin analysis shows SMB products average 30% margin, so the 20% discount cuts unit profit roughly in half. Penetration is 80%: nearly every SMB order is discounted. The finding is not "discounts are moderate" but "discounting is quietly destroying SMB margin," which points to a specific action (cap discount depth or reduce penetration).
+
+The discipline: never conclude a discount is "small" or "fine" from the revenue view alone. Always translate it to margin impact and check both depth and penetration before making a pricing recommendation.

package/assets/skills/authored/data-analysis/composable/mini/06-insight-generation.md

@@ -0,0 +1,25 @@
+---
+pairs-with:
+  - 07-executive-writing.md
+  - 08-recommendations.md
+---
+
+# Generating Insight Beyond Aggregates
+
+A table of totals is not analysis. Insight answers "so what?" Push every number one level further.
+
+Four moves that turn a number into a finding:
+- **Compare**: vs. prior period, vs. target, vs. benchmark, vs. other segments. A number alone ("revenue was $2M") means nothing without a reference point. Is $2M good? Only a comparison tells you.
+- **Decompose**: break a change into its drivers: price × volume, new × existing customers, which segments moved. "Revenue up $200k" becomes "driven entirely by Enterprise upsell; SMB actually shrank."
+- **Explain**: offer the most likely cause and note what would confirm or refute it. Distinguish observation from hypothesis.
+- **Quantify impact**: translate to money, users, or risk, and to the decision at stake. "This costs ~$120k/quarter in margin" lands; "discounts are high" doesn't.
+
+Then **surface the surprising**: the outlier, the reversal, the concentration, the thing that contradicts the assumption. That is where the value lives. A finding that confirms what everyone already believed rarely changes a decision.
+
+**Test for every finding:** ask "so what should we do differently?" If a number implies no decision, it may be context, not a finding: demote it to background.
+
+**Worked example.** Draft says: "Q3 revenue was $2.0M. North America was $1.2M. Enterprise was $1.4M." That is three facts, no insight. Pushed further: "Q3 revenue grew 12% ($1.8M → $2.0M), but *all* net growth came from Enterprise (+$260k); SMB declined $60k for the second straight quarter (the first sign the SMB motion is stalling and worth investigating before Q4 planning)." Same underlying numbers, but now there is a comparison, a decomposition, a likely story, and a decision implication.
+
+**Second example.** "Average order value is $850" is a bare aggregate. Insight: "AOV is $850, but the median is $210 (a handful of enterprise deals pull the mean up 4x). For SMB-focused decisions, use the median; the $850 figure will mislead capacity and pricing planning." The move here is recognizing the distribution and stating the consequence for a decision.
+
+The discipline: never ship a bare number. Attach a comparison and a "so what" to every figure that reaches the reader.

package/assets/skills/authored/data-analysis/composable/mini/07-executive-writing.md

@@ -0,0 +1,26 @@
+---
+pairs-with:
+  - 08-recommendations.md
+  - tech-writing/05-style-clarity.md
+---
+
+# Writing for Executive Audiences
+
+Executives read for decisions, not for your method. Structure and language should serve a busy reader who will act on three sentences.
+
+- **Lead with the answer (BLUF: bottom line up front).** The headline finding and its implication come first; supporting detail follows. Never make a reader wade through methodology to reach the conclusion. If they read only the first line, they should get the point.
+- **Quantify and contextualize.** "Revenue grew 12% ($1.8M → $2.0M), driven mostly by Enterprise," not "revenue grew." Every claim carries a number and a reference point.
+- **Three-to-five findings, ranked by impact.** A report with 20 equal bullets has no priorities. Lead with what matters most; cut or appendix the rest.
+- **Round appropriately.** Say "$2.0M," not "$2,013,847.22." Spurious precision signals poor judgment and slows the reader. Match precision to the decision.
+- **Translate to the business.** Tie every metric to revenue, cost, risk, or growth. Replace jargon and raw metric names with plain business language: "customers who stopped using us" beats "MAU churn delta."
+- **Visual discipline.** One chart, one message; label it with the takeaway ("Enterprise now 70% of revenue"), not just "Figure 3." If a chart needs a paragraph to interpret, it's the wrong chart.
+
+**Worked example (before/after opening):**
+- Before: "We queried the transactions table for Q3, deduplicated on order ID, excluded refunds, and after grouping by segment we observed the following distribution of revenue..."
+- After: "**Q3 revenue hit $2.0M (+12%), but growth is now entirely Enterprise: SMB shrank for the second quarter.** Details below." The method belongs in an appendix or a footnote, not the lead.
+
+**Second example (precision and translation):**
+- Before: "Net revenue retention was 1.1372 for the enterprise cohort."
+- After: "Enterprise customers grew ~14% in spend without any new logos: existing accounts are expanding, which de-risks the Q4 number."
+
+The discipline: write the one sentence you'd want the CEO to repeat in a meeting, put it first, and make everything else support it.

package/assets/skills/authored/data-analysis/composable/mini/08-recommendations.md

@@ -0,0 +1,20 @@
+---
+pairs-with:
+  - 06-insight-generation.md
+---
+
+# Recommendations & Framing
+
+A recommendation is where analysis becomes value, and where analysts most often overreach or under-deliver.
+
+- **Recommendations must follow from the data shown**, not appear from nowhere. Each should trace to a specific finding in the report. If a reader can't point to the number behind a recommendation, it's an opinion, not analysis.
+- **Be specific and actionable.** "Cap SMB discounts at 15%, projected to recover ~$120k in annual margin," not "improve discounting." A good recommendation names the action, the target, and the expected impact.
+- **Acknowledge uncertainty and tradeoffs.** State your confidence and what could change the conclusion. Overclaiming from correlation destroys credibility faster than admitting a limit. "This assumes discount elasticity is low, which we haven't tested" is a strength, not a weakness.
+- **Prioritize by impact and effort.** Rank recommendations; don't hand over a flat list of ten. Lead with high-impact, low-effort moves.
+- **Separate what the data says from what you infer.** "Discounted orders are 2x larger (observed)" is a fact; "so discounts likely drive larger orders (hypothesis, needs a controlled test)" is an inference. Label each. Conflating them is how correlation gets sold as causation.
+
+**Worked example.** Finding: SMB discount penetration is 80% at 20% average depth, and SMB margin is ~30%, so discounting roughly halves SMB unit profit. Recommendation: "Pilot a 15% discount cap on SMB for one quarter in two regions; projected to recover ~$120k annualized margin if volume holds. Risk: if SMB volume is discount-elastic, we may lose orders; the pilot's control regions will measure this. Confidence: medium; we have the margin math but not the elasticity." Notice it traces to the finding, quantifies impact, names the risk, states confidence, and proposes a test rather than a blanket rollout.
+
+**Counter-example to avoid:** "Discounts are hurting us, so stop discounting." No target, no quantified impact, ignores that discounts may drive volume, and overclaims causation. It would likely be wrong and would erode trust in the whole report.
+
+The discipline: for every recommendation, be able to say which finding it rests on, what it's worth, how confident you are, and what would prove it wrong.

package/assets/skills/authored/data-analysis/composable/mini/09-reproducibility-assumptions.md

@@ -0,0 +1,20 @@
+---
+pairs-with:
+  - 01-data-quality-profiling.md
+---
+
+# Reproducibility & Stating Assumptions
+
+An analysis nobody can reproduce or trust is worthless, however clever the method.
+
+- **State every assumption**: date range, filters applied, how nulls/outliers/duplicates were handled, currency, timezone, and the definition of each metric ("active" = ?). Assumptions left unstated silently make numbers non-comparable across reports and people.
+- **Define metrics precisely.** "Revenue": gross or net of refunds? Booked or recognized? Including tax or not? Two analysts with different definitions produce different totals and both look correct. Pin the definition down and write it near the number.
+- **Make it re-runnable.** Deterministic steps, a fixed seed for any sampling, and the data source plus snapshot date recorded. Someone else running your steps on the same data must get the same numbers. If a rerun tomorrow gives a different answer, say why (live data) and pin a snapshot.
+- **Show denominators and sample sizes** so a reader can judge reliability. "12% conversion" means little without knowing it's 12 of 100 vs. 12,000 of 100,000.
+- **Sanity-check before publishing.** Do totals reconcile to a known source (e.g., does your revenue sum match finance's)? Do the parts sum to the whole? Does the number pass a smell test against prior periods? Reconciliation catches the duplicated-join and wrong-filter errors that pass silently otherwise.
+
+**Worked example.** A report states "Q3 revenue: $2.0M." Reproducible version: "Q3 revenue (net of refunds, recognized, USD): $2.03M. Source: `transactions` snapshot 2026-10-02, deduplicated on order_id (1,200 dupes removed), refunds excluded (−$140k), 12% of rows had null region and are grouped as 'Unknown'. Reconciles to finance's GL within 0.5%." A reader can now trust it, reproduce it, and compare it to next quarter on the same basis.
+
+**Why it matters.** The difference between trustworthy reporting and a plausible-looking guess is not cleverness: it's that the trustworthy one states its assumptions, defines its metrics, reconciles to a known truth, and can be re-run to the same result. When two reports disagree, the one that documented its basis wins the argument.
+
+The discipline: before publishing, write down the date range, filters, null/outlier/duplicate handling, and metric definitions, then reconcile the headline number against an independent source.