dsh-plugin-t-expert 0.4.51 → 0.4.53

package/data/experts/engineering/data-analytics-reporter/skills/data-quality-assessment/SKILL.md

@@ -1,167 +0,0 @@
----
-name: data-quality-assessment
-description: "Assess whether datasets are trustworthy for analysis, modeling, dashboards, or pipelines; and validate finished analyses before sharing. Use for data quality checks (grain, freshness, nulls, duplicates, schema drift, joins, integrity, distributions) and analysis QA (methodology review, calculation verification, visualization checks, confidence assessment)."
----
-
-# Data Quality Assessment & Analysis Validation
-
-Two complementary capabilities: (1) assess whether a dataset is trustworthy enough for its intended use, and (2) validate a finished analysis before it is shared with stakeholders.
-
-## Part A: Data Quality Assessment
-
-Assess whether a dataset is trustworthy enough for analysis, modeling, dashboards, experiments, or downstream pipelines. Start with the intended use and grain, run the highest-value checks for the data shape, and report concrete evidence, analytical risk, likely causes, and the smallest useful remediation or automated test.
-
-### Workflow
-
-1. **Clarify the quality question and operating context.**
-
-   Establish what the dataset represents, the intended unit of analysis, the downstream use, whether the user cares about raw ingestion quality, transformed-model quality, or both, and the comparison baseline. Identify expected grain, primary keys, important date columns, timezone assumptions, domain rules, allowed values, and business thresholds. If context is missing, infer cautiously and label assumptions.
-
-2. **Choose an inspectable analysis path.**
-
-   When checks require SQL or Python, default to a companion notebook or script so the user can inspect the exact code behind the findings. For queryable tables, confirm schema, grain, sample rows, and query rules before heavier checks.
-
-3. **Build a compact profile.**
-
-   Start with row count, column count, column names and types, candidate keys, duplicate rates on likely identifiers, min/max timestamps, null rates, distinct counts for categorical columns, and basic numeric summaries. Confirm grain before interpreting anomalies; many apparent quality problems are mixed-grain data, partial backfills, late-arriving data, or duplicated joins.
-
-4. **Run core quality checks.**
-
-   Select checks that match the dataset and task across completeness, uniqueness, validity, consistency, integrity, timeliness, volume, and shape. Compare rates, not just counts, and segment by time, source, country, platform, or other key dimensions when that helps distinguish real issues from expected variation.
-
-5. **Run shape-specific checks.**
-
-   Adapt the checks to the data shape:
-   - **Event data**: duplicate event IDs, future timestamps, coverage gaps, abrupt event-mix changes after releases.
-   - **Dimension tables**: non-unique business keys, orphan surrogate keys, status changes without timestamps, unexpected churn in reference values.
-   - **Fact tables**: mixed grain, impossible measures (negative revenue/quantity), join blowups, late-arriving partitions.
-   - **ML feature tables**: leakage from post-outcome fields, feature sparsity spikes, range shifts, class-label drift.
-   - **Experiment data**: duplicate assignments, variant imbalance, exposure without assignment, events before assignment.
-
-6. **Run temporal and distribution checks when history exists.**
-
-   Prioritize temporal diagnostics when the user mentions "after X date", "suddenly", "recently". Check first-seen/last-seen dates, daily null-rate trends, duplicate-rate trends, row count trends, category-share shifts, distribution drift, and change points around launches, migrations, or incidents.
-
-7. **Investigate analytical risks and likely causes.**
-
-   Tie each issue to downstream risk: broken analysis, biased decisions, broken joins, stale dashboards, incorrect experiments, leakage, or misleading segments. Identify whether the issue is isolated to a source, segment, partition, time window, or pipeline change.
-
-8. **Recommend fixes or automated tests.**
-
-   Recommend the smallest set of fixes, monitoring, or automated tests that would materially reduce risk. Suggest automation only when the rule is stable and worth maintaining.
-
-### Core Check Categories
-
-- **Completeness**: null rate by column/partition/segment; unexpected empty strings or sentinel values; required-column population rate.
-- **Uniqueness**: exact duplicate rows, duplicate primary keys, duplicate composite keys, proportion unique for semi-unique fields.
-- **Validity**: type conformance; format checks for IDs, emails, URLs, enums, timestamps; range checks for measures and dates; allowed-values checks.
-- **Consistency**: cross-field rule checks, units/currency consistency, status-timestamp alignment, agreement between duplicated fields.
-- **Integrity**: parent-child key coverage, orphan records, unexpected many-to-many joins, broken SCD joins.
-- **Timeliness**: freshness lag, missing recent partitions, unexplained historical rewrites or backfills.
-- **Volume and shape**: row-count drift, distinct-count drift, distribution drift, share-of-total drift, new/disappeared categories.
-
-### Severity Classification
-
-- **Critical**: breaks trusted analysis, core joins, production dashboards, or key decisions.
-- **High**: materially biases downstream decisions (large null spikes, category drift, leakage).
-- **Medium**: localized or explainable issues needing documentation or monitoring.
-- **Low**: cosmetic inconsistencies, expected sparsity, or known edge cases.
-
-### Automated Test Guidance
-
-Good candidates: primary key uniqueness, not-null checks on required columns, accepted values for stable enums, referential integrity, freshness thresholds, seasonality-aware row-count bounds.
-
-Use caution with: hard-coded distribution thresholds on volatile metrics, strict uniqueness in messy entity-resolution cases, recent partitions when late-arriving data is normal.
-
-### Output Structure
-
-1. Dataset and grain summary
-2. Checks performed
-3. Findings (with evidence: counts, rates, segments, dates)
-4. Temporal or trend anomalies
-5. Likely causes and impacted use cases
-6. Recommended fixes or automated tests
-7. Assumptions and open questions
-
----
-
-## Part B: Analysis Validation (QA)
-
-Validate an analysis before sharing with stakeholders. Focus on whether the question, data, methodology, calculations, visuals, claims, caveats, and recommendations are trustworthy enough for the stated audience and decision.
-
-### Workflow
-
-1. **Inventory the artifact and claims.**
-
-   Identify the report, notebook, spreadsheet, SQL, dashboard, or recommendation being validated. Extract the main question, audience, decision, key claims, headline numbers, data sources, time windows, populations, filters, and stated caveats.
-
-2. **Validate question, methodology, and assumptions.**
-
-   Confirm the analysis answers the stated question (not a nearby easier one). Check population, eligibility rules, exclusions, sampling, metric definitions, formulas, units, denominators, timezones, cohorts, comparison periods, and baselines.
-
-3. **Validate data selection and quality risks.**
-
-   Confirm that chosen tables/files are appropriate and current. Check freshness, partitions, segment coverage, completeness, null handling, deduplication, filter logic, and join coverage.
-
-4. **Verify calculations and aggregations.**
-
-   Recompute highest-impact numbers independently. Check grain, subtotals, denominators, rate bases, period-over-period bases, weighted averages, units, and whether categories add to totals. For SQL, inspect join types, group-by grain, filters, distinct counts.
-
-5. **Test reasonableness and common traps.**
-
-   Compare magnitudes against known baselines. Investigate trend jumps, flatlines, exact round numbers, 0%/100% rates. Check edge cases.
-
-6. **Review visuals and presentation integrity.**
-
-   Confirm charts use appropriate types, scales, axes, titles, labels, ordering, and color. Check whether a quick reader could get a misleading interpretation.
-
-7. **Evaluate narrative, conclusions, and recommendations.**
-
-   Confirm conclusions are supported by evidence. Separate findings from interpretation. Identify alternative explanations and unsupported causal language.
-
-8. **Produce confidence assessment and required fixes.**
-
-   Prioritize issues by decision impact.
-
-### Common Pitfalls
-
-- **Join explosion**: many-to-many joins silently multiply rows.
-- **Survivorship bias**: only includes entities that exist today.
-- **Incomplete period comparison**: partial vs. complete period.
-- **Denominator shifting**: eligible population changes between compared groups.
-- **Average of averages**: pre-computed averages averaged without weighting.
-- **Timezone mismatch**: different timestamp conventions or cutoffs.
-- **Selection bias**: segments defined by the outcome being measured.
-- **Simpson's paradox**: aggregate and segment-level trends conflict.
-
-### Confidence Ratings
-
-- **Ready to share**: Methodologically sound, key calculations verified, caveats clear.
-- **Share with caveats**: Directionally usable but specific limitations must be communicated.
-- **Needs revision**: Material errors, unsupported claims, or methodological issues.
-
-### Validation Report Template
-
-```markdown
-## Validation Report
-
-### Overall Assessment: [Ready to share | Share with caveats | Needs revision]
-
-### Methodology Review
-[Findings about question framing, data selection, population, definitions, comparisons.]
-
-### Issues Found
-1. [Severity: High/Medium/Low] [Issue, evidence, and impact]
-
-### Calculation Spot-Checks
-- [Metric]: [Verified / Discrepancy found / Not verified] - [evidence]
-
-### Visualization Review
-[Chart or presentation issues, if applicable.]
-
-### Suggested Improvements
-1. [Improvement and why it matters]
-
-### Required Caveats for Stakeholders
-- [Caveat that must be communicated]
-```

package/data/experts/engineering/data-analytics-reporter/skills/data-visualization/SKILL.md

@@ -1,94 +0,0 @@
----
-name: data-visualization
-description: "Design, specify, implement, revise, and QA quantitative visuals and chart choices. Use when an analytical answer needs visual judgment—comparing values, showing composition, reading concentration, understanding movement over time, or building chart specifications for reports and dashboards."
----
-
-# Data Visualization
-
-Create quantitative visuals that are analytically sound, immediately readable, and polished enough to ship in a report, memo, slide, dashboard, notebook, or HTML artifact. Treat charts as evidence for a takeaway. Redesign charts that are visually attractive but analytically weak, and revise charts that are technically correct but hard to interpret.
-
-## Chart Selection Guide
-
-| Data relationship | Best chart | Use it well |
-|---|---|---|
-| Trend over time | `line` | Show enough points to reveal shape; use `area` only when filled magnitude helps; `sparkline` for dense KPI cards |
-| Composition over time | `stackedArea` | Use when parts should read as one total; switch to `line` when comparing trajectories matters more |
-| Comparison across categories | `bar` | Sort when order is not semantic; horizontal bars for long labels; avoid redundant legends |
-| Ranking or top-N | `leaderboard` | Compact, single-measure; switch to ranked `bar` for more context |
-| Part-to-whole composition | stacked `bar` | Keep denominator explicit; use `pie` only for rough read with few slices |
-| Distribution or spread | `histogram` | Numeric bins that reveal shape; `boxPlot` when comparing groups is the point |
-| Distribution across groups | `boxPlot` | Median and spread over full shape; switch to `histogram` when shape needs space |
-| Relationship between variables | `scatter` | Numeric x and y, enough distinct points to show pattern; retain labels and one grouping candidate |
-| Dense 2D pattern or cohort matrix | `heatmap` | Matrix shape or intensity; switch to `scatter` for point-level variation |
-| Additive bridge start to end | `waterfall` | Only when drivers sum cleanly to end value; otherwise ranked `bar` |
-| Ordered stage progression | `funnel` | Only for ordered single-series stages; prefer stage `bar` when geometry distorts |
-
-## Workflow
-
-1. **Define the analytical question and takeaway** before choosing a chart. Identify the intended comparison and context needed to make the visual honest.
-
-2. **Choose the simplest defensible chart family** from the Chart Selection Guide. Keep the top-level families small: Tables & Scorecards, Trend, Comparison & Ranking, Composition, Distribution, Relationship, Uncertainty & Benchmark, Matrix & Cohort, Decomposition & Progression.
-
-3. **Write a compact chart contract** before implementation:
-   - Analytical question and takeaway
-   - Chart family and concrete variant
-   - Data sufficiency for the chosen visual
-   - Palette policy and non-color distinction plan
-   - Output footprint and delivery target
-
-4. **Select the delivery path** matching the final surface:
-   - Static HTML/PNG for reports and portable files
-   - Python (Matplotlib/Seaborn) for notebooks and static exports
-   - JavaScript (ECharts, Chart.js, D3) for interactive web dashboards
-   - BI-native widgets when a governed BI tool owns rendering
-
-5. **Build in order**: format → structure → color → QA.
-
-6. **Render or export** the chart in its real context. Save the image format the delivery surface expects.
-
-7. **Inspect in final context**. Revise before delivery when the chart, labels, color, or container fails QA.
-
-## Selection Rules
-
-- Start from the analytical question, not a favorite chart type.
-- Use charts for shape and comparison; tables for exact lookup.
-- Do not choose `line` merely because "trend" appears—decide whether the reader needs status, movement, variance, mix, or distribution.
-- Do not ship underpowered trend charts. Aim for at least 8-12 temporal points. Use KPI cards, grouped bars, or narrative for fewer points.
-- Do not ship underpowered scatter charts. Aim for at least 12-20 meaningful points.
-- Use horizontal bars for long labels; sorted bars when order has no semantic meaning.
-- Prefer variant escalation within a family before inventing new chart types.
-- Keep pie, Pareto, waterfall, Likert as variants, not defaults.
-- Include volume/denominator/sample-size context when omission could mislead.
-
-## Visual Design Standards
-
-### Typography & Color
-- Single font family across charts. Prefer white/near-white backgrounds, quiet grey grid lines, deep charcoal text, restrained palette.
-- Do not rely on color alone. Use tone, open fill, marker fill, line style, direct labels, ordering, or faceting.
-- Choose one palette policy before plotting:
-  - **Single-root preferred**: one non-neutral root plus shades for simple charts.
-  - **Hard two-root cap**: at most two non-neutral roots for binary, signed, or comparison charts.
-  - **Relaxed multi-category**: up to five approved roots when category identity is the point.
-
-### Layout & Labels
-- Chart titles: neutral and descriptive for reports/dashboards; takeaway-led for standalone charts.
-- Put metric details (units, denominator, date range, cohort, filters) in the subtitle.
-- Prefer direct labels when they reduce legend lookups; use compact legend when direct labels create clutter.
-- Reserve space for horizontal bars with long labels or negative values.
-- Do not use gradients inside marks, colored backgrounds, or inconsistent corner radii.
-
-### Signed Values
-- Avoid green/red by default. Use dark vs. open/light fills, direct signed labels, and clear zero-line context.
-- Waterfall: matched neutral anchors + exactly two non-neutral delta colors.
-
-## Quality Bar
-
-Before delivery, confirm:
-- Chart choice follows the analytical question, not visual preference.
-- Form matches the comparison; scales stay honest and consistent.
-- Data grain, filters, date range, denominator, and units match the supported claim.
-- Every shipped chart has a visible title and subtitle with needed context.
-- Labels, ticks, legends, annotations must not collide or clip.
-- Multi-series marks have distinct tones/fills/styles legible in grayscale.
-- Positive/negative states use tone + signed labels, not just color.
-- Inspect the visual in the final layout before handoff.

package/data/experts/engineering/data-analytics-reporter/skills/kpi-design/SKILL.md

@@ -1,134 +0,0 @@
----
-name: kpi-design
-description: "Design KPI frameworks, set targets, develop measurement plans, and estimate market/opportunity sizes (TAM/SAM/SOM). Use when success metrics, drivers, guardrails, targets, or measurement approach need to be defined or improved, or when a market or opportunity size estimate is needed."
----
-
-# KPI Design & Market Sizing
-
-Two complementary capabilities: (1) design KPI frameworks, set targets, and develop measurement plans; (2) estimate market or opportunity sizes with transparent assumptions and sensitivity analysis.
-
-## Part A: KPI Framework Design
-
-Design KPI frameworks, set targets, and develop measurement plans that help teams make product or business decisions.
-
-### Workflow
-
-#### 1. Clarify The Decision And Operating Context
-
-Understand the decision the metrics need to support, the context in which they will be reviewed, and who will act on the result. Ask the user to clarify the goal, operating cadence, or measurement constraints when missing input would change the recommendation.
-
-#### 2. Gather Evidence Before Recommending Metrics
-
-When the prompt does not already provide enough context to know what success means, gather that context before recommending metrics or targets. Understand the goal, current state, audience, constraints, risks, existing definitions, prior decisions, and any baseline or target context.
-
-#### 3. Generate A Wider Candidate Set
-
-Create candidate outcome, driver, and guardrail metrics before narrowing. Each candidate should have a clear definition and a plausible link to the decision.
-
-#### 4. Compare And Select Metrics
-
-Compare candidate metrics by whether they:
-- **Reflect the goal**: the metric represents the intended outcome. When using a proxy, explain why and where it could mislead.
-- **Inform a real decision**: movement should change what the team does.
-- **Show useful signal at the decision cadence**: not too slow-moving or noisy for the decision it supports.
-- **Can be influenced by the team**: plausible levers exist, or paired with drivers.
-- **Can be measured operationally**: instrument, calculate, and track consistently.
-- **Are hard to game**: improving the metric should not hide harm to quality, trust, or retention.
-
-Recommend 1-3 primary KPIs, 1-2 driver metrics for each KPI, and 1-2 guardrails when tradeoffs are likely.
-
-For each recommended metric: what it measures, why it matters, how it is calculated, where it comes from, main pros and cons, and what caveats matter.
-
-#### 5. Set Targets When Needed
-
-Treat target setting as separate from metric selection.
-
-Use the target-setting approach that fits the evidence:
-- **Top-down**: benchmarks, historical performance, comparable products, competitor context.
-- **Bottom-up**: what the team can realistically do—what is shipping, expected adoption, available levers.
-
-Compare aspirational targets with realistic influence. A good target should be meaningful for the decision and plausible enough to guide action.
-
-#### 6. Deliver The Recommendation
-
-Compact metric-design brief:
-1. Initiative summary
-2. Recommended metric candidates with definition and rationale
-3. Target recommendation with anchor, assumptions, and methodology
-4. Evidence reviewed
-5. Assumptions and missing context
-6. Risks and guardrails
-7. Open questions
-
-### Example Metric Shapes
-
-- **Product launch/adoption**: outcome metric for adoption + drivers for activation/engagement + guardrails for experience quality.
-- **Growth work**: business outcome (activation/retention/monetization) + drivers + guardrails.
-- **Funnel work**: progression/completion outcome + stage drivers + downstream quality guardrails.
-- **Operating review**: health, pacing, action-oriented metrics.
-- **Experiment**: one primary success metric + diagnostics + guardrails for unintended effects.
-- **Platform/reliability**: service health, throughput, quality, cost efficiency, customer impact.
-
----
-
-## Part B: Market Sizing
-
-Produce defensible estimates of a market or opportunity from available context, public sources, transparent assumptions, and auditable calculations.
-
-### Workflow
-
-#### 1. Frame The Market Or Opportunity
-
-Define the boundary:
-- What is being sized (product category, workflow, problem, use case)
-- Where and when (geography, segment, time horizon, maturity)
-- Who counts (relevant population, unit of demand, transaction type)
-- How measured (spend, revenue, volume, value created)
-- What answer needed (TAM/SAM/SOM, market entry, expansion upside, spend pool)
-
-#### 2. Choose A Sizing Approach And Inputs
-
-Pick the simplest sound approach:
-- **Top-down**: reliable aggregate market data exists.
-- **Bottom-up**: market can be built from observable units and assumptions.
-- **Value-based**: estimate from value created rather than published market total.
-
-Use mixed approach only when cross-checking would materially improve confidence.
-
-#### 3. Gather Sources For The Inputs
-
-Start with user-named sources. Then use strongest available evidence for each major input. When an input depends on the outside market, use public sources for benchmarks, population estimates, comparable markets, or proxy assumptions.
-
-If the strongest source is unavailable, continue with a transparent proxy assumption only when the estimate is still useful. Label the gap.
-
-#### 4. Separate Facts From Assumptions
-
-Keep sourced facts, inferred estimates, and judgment calls distinct. When exact data is unavailable, use a defensible proxy, explain why it is reasonable, and note confidence level.
-
-#### 5. Build The Model
-
-Make the model easy to inspect and adjust:
-- Market definition and measurement unit
-- Assumptions and source context
-- Calculation chain and derived values
-- Base case, material ranges, and sensitivity logic
-- Validation priorities
-
-Keep derived values traceable to formulas rather than hardcoded outputs.
-
-#### 6. Test Sensitivity
-
-Identify assumptions that move the estimate most. Show how the estimate changes when those assumptions vary. Prefer simple, decision-useful sensitivity over exhaustive scenario sprawl.
-
-Use ranges when uncertainty is material. Do not hide uncertainty behind a single point estimate.
-
-#### 7. State The Estimate And Validation Priorities
-
-Close with:
-- Market definition
-- Estimate or range
-- Method
-- Main uncertainty drivers
-- Sensitivity takeaways
-- Validation priorities
-- Practical interpretation for the user's decision

package/data/experts/engineering/data-analytics-reporter/skills/metric-diagnostics/SKILL.md

@@ -1,143 +0,0 @@
----
-name: metric-diagnostics
-description: "Diagnose why a metric changed or differs from expectation, and produce leadership-ready KPI updates. Use when the user needs to understand what drove a metric movement, anomaly, or discrepancy, or when producing WBR/MBR/QBR summaries, scorecards, target pacing readouts, or performance updates."
----
-
-# Metric Diagnostics & KPI Reporting
-
-Two complementary capabilities: (1) diagnose why a metric changed or differs from expectation, and (2) produce leadership-ready KPI updates and scorecards.
-
-## Part A: Metric Diagnostics
-
-Diagnose why a metric changed or differs from expectation. Reproduce the metric, define the comparison, quantify the movement, validate likely drivers, and state what is verified, likely, unresolved, and useful to do next.
-
-### Workflow
-
-#### 1. Define The Diagnostic Question
-
-Frame the diagnostic so it is clear what changed and what comparison would prove it.
-
-Define:
-- What the metric means in business terms
-- The time window and comparison that make the change measurable
-- The population and grain that determine what counts
-- The source that owns the metric definition
-- The diagnostic question (movement, concentration, or reconciliation)
-
-#### 2. Validate The Metric Definition And Source
-
-Before explaining the movement, confirm that the metric is defined correctly and that the source data can measure it reliably. Confirm definition, grain, aggregation logic, filters, joins, exclusions, freshness, and lineage.
-
-Treat saved context and familiar table names as source candidates, not source selection. Inspect at least one business-facing surface and one lower-level source, then state why the selected source owns the answer.
-
-#### 3. Establish The Metric Pattern
-
-Before looking for drivers, establish the metric pattern the diagnostic needs to explain. Quantify the metric over the relevant period and scope. If the question includes a comparison, reproduce that comparison.
-
-Do not search for causes until the size, timing, and scope of the pattern are verified.
-
-#### 4. Choose The Diagnostic Plan
-
-Choose the smallest set of cuts and checks likely to explain the pattern. Choose driver dimensions from the metric's operating logic, business context, and source shape. Prioritize drivers the business usually monitors or can act on.
-
-Use the explanation mode that fits the question:
-- **Metric change**: compare focal window with baseline, rank segment contributions, check mix shift vs. within-segment movement.
-- **Spike/regression/incident**: pin down onset, peak, recovery, distribution shape, affected slices, broad vs. localized degradation.
-- **Largest contributors**: define "largest", rank entities, compare total share and change, look for major movers, entrants, and exits.
-- **Reconciliation**: align definitions, filters, grain, numerator, denominator; quantify components explaining the gap.
-
-#### 5. Decompose And Validate Drivers
-
-Quantify the main drivers and validate whether they explain the pattern.
-
-- Size each major driver with the strongest available evidence.
-- Show whether it explains the pattern, how large it is relative to the base.
-- For rates, check whether the numerator, denominator, or both explain the change.
-- For additive metrics, calculate contribution share when it sharpens the story.
-- Separate composition effects from within-segment performance effects.
-- Treat measurement issues as possible explanations (logging changes, incomplete data, duplicated rows, shifted denominator).
-- Calibrate the explanation to the evidence; make important uncertainty visible.
-
-#### 6. State Implications And Follow-Up
-
-Lead with the answer to the diagnostic question, then state practical implications:
-- The pattern being explained
-- The strongest driver explanation and supporting evidence
-- Why it matters for the business
-- How much confidence to place in the explanation
-- The implication, next action, or follow-up that matters most
-
----
-
-## Part B: KPI Reporting
-
-Turn business or product metrics into decision-ready operating readouts for leaders and teams. Define the KPI contract, report status against the right comparison and target, include validated driver context, and state the operating implication clearly.
-
-### Workflow
-
-#### 1. Clarify The Readout Purpose
-
-Understand who the readout is for, what conversation it supports, and what is being reported. Anchor the update in the period being evaluated, the comparison or target, and the freshness cutoff.
-
-#### 2. Define The Metric Framework
-
-Decide which metrics belong in the readout and what role each plays. Start with the primary KPI, then add the smallest set of supporting metrics to explain status.
-
-Lead with the metric that matters most to the audience. Include the metrics and slices decision-makers actually use, plus any that materially explain this update.
-
-#### 3. Lock Metric Definitions And Sources
-
-Confirm the KPI definition, source, time window, reporting cutoff, comparison period, and target or pacing expectation before interpreting performance.
-
-If a definition changed, show comparable restated history or call out the break clearly.
-
-#### 4. Pull The Topline Actuals
-
-Query or inspect data sources for core actuals. Reproduce the topline actual before explaining movement.
-
-For each headline KPI, include the current value, absolute and relative change vs. the comparison period, and short interpretation. Call out anything that makes the current value hard to compare.
-
-#### 5. Put The Numbers In Context
-
-Compare actuals against the context that makes performance interpretable: target, plan, pacing model, benchmark, historical range, or relevant peer group.
-
-If the goal has a deadline, show whether it is on pace. Include absolute and percent variance to target and a status indicator.
-
-#### 6. Explain Validated Drivers
-
-Driver claims must be validated before presented as explanations. Use Part A (Metric Diagnostics) to identify and validate drivers when fresh investigation is needed.
-
-#### 7. Add Business Context And Operating Implications
-
-Translate evidence, driver analysis, and business context into the operating implication. State whether the movement is concerning, what next step is warranted, and whether the KPI is on track, at risk, or ahead of plan.
-
-#### 8. Shape The Readout
-
-Common shapes: inline written update, document/report, slide, or deck. Adapt to the audience, evidence, and artifact.
-
-### KPI Reporting Standards
-
-#### Metric Standards
-- Never present a KPI as precise when its definition, source, or comparison basis is unclear.
-- Make calculation logic, inclusion rules, grain, and time treatment explicit.
-- Reconcile totals and compare against prior reporting when possible.
-- Do not compare periods that are not definitionally compatible.
-
-#### Status And Pacing Standards
-- Include headline takeaway, current actual, comparison, target/pacing context, driver summary, and implication.
-- Put actuals next to target so the reader can judge performance immediately.
-- If a target is time-bound, show whether current performance is on pace.
-- Use traffic-signal status only when it helps prioritize action.
-
-#### Driver Standards
-- Quantify drivers whenever evidence supports it.
-- Report the few drivers that matter for interpreting the movement.
-- Separate validated drivers from business context or hypotheses.
-- Do not elevate business events into causes unless timing and measured change support the link.
-- State whether movement is broad-based or concentrated.
-
-#### Presentation Standards
-- Write for executives who skim: lead with the answer, then evidence.
-- Use business-readable numbers: `123k (+8% w/w, +19% m/m)`.
-- Replace generic adjectives ("strong", "healthy") with metric evidence.
-- Keep caveats close to the claim they affect.