dsh-plugin-t-expert 0.4.48 → 0.4.53

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

@@ -1,213 +0,0 @@
----
-name: analytics-reporting
-description: "Build polished analytical reports, dashboards, and product/business analyses. Use when the user needs a durable report (executive or technical), an analytical dashboard with clear metrics, or a data-backed product/business analysis to inform decisions. Covers report building, dashboard construction, and decision-oriented quantitative analysis."
----
-
-# Analytics Reporting & Dashboard Building
-
-Three complementary capabilities: (1) build polished analytical reports, (2) construct source-backed dashboards, and (3) perform decision-oriented product/business analysis.
-
-## Part A: Report Building
-
-Build polished analytical reports for executive, product, business, and technical audiences. The report owns the reader-facing narrative, audience shape, evidence placement, visual/table placement, caveats, source metadata, and handoff.
-
-### Workflow
-
-#### 1. Define The Reporting Job
-
-State the user question, decision the report should support, primary audience, scope, time frame, comparison baseline, and what would make the report decision-useful.
-
-Choose exactly one audience:
-- **Product stakeholders**: default for product, business, leadership, strategy, diagnostics, KPI readouts.
-- **Technical**: only when user asks for technical/methods-first report.
-
-#### 2. Gather And Bound The Evidence
-
-Inventory source data, metric definitions, denominators, assumptions, caveats, notebooks, SQL, and scripts needed. Resolve ambiguities before drafting claims. If a metric cannot be supported, record why.
-
-#### 3. Distill The Report Spine
-
-Write a compact answer-first report spine:
-- Question
-- Decision-useful answer
-- Metric, cohort, denominator, time window, comparison basis
-- Findings by segment or driver with evidence
-- Sensitivity or validation checks
-- Caveats that could change interpretation
-- Recommended next step or open question
-
-#### 4. Plan Reader-Facing Structure
-
-Draft ordered major segments, visible titles, and intended evidence format. Use visuals by default for quantitative findings; tables for exact lookup.
-
-Apply the report depth gate:
-- Executive summary does not count as evidence section.
-- Comparative reports need segment-level interpretation.
-- Claims need at least one validation note near the finding.
-
-#### 5. Design Visuals And Tables
-
-Route every report visualization through the data-visualization skill for chart selection and QA. Every visual/table should support a specific claim. Plan an adjacent explanatory paragraph for every visualization.
-
-#### 6. Build The Delivery Surface
-
-Choose delivery mode:
-- **HTML report**: portable static HTML with embedded chart images. Self-contained, can be opened directly in browser.
-- **Markdown report**: structured markdown suitable for documentation or further processing.
-
-#### 7. Validate The Finished Report
-
-Confirm:
-- Top of report answers the user directly
-- Every major segment has a visible title
-- Claims, visuals, tables, caveats appear in intended reading order
-- Evidence and source notes are sufficient for auditability
-
-### Report Standards
-
-#### Narrative
-- Open stakeholder reports with executive summary that answers the question directly (2-4 bullets with bold topic sentences).
-- Open technical reports with main result, then definitions, methods, uncertainty, limitations.
-- Start major segments with the takeaway, not setup prose.
-- Keep report reading path top-to-bottom, single-column by default.
-- Pair each important number or visual with plain-English interpretation.
-- Include recommended next steps when evidence supports action.
-
-#### Evidence And Sources
-- Base every claim on saved data, code, query results, or rendered charts.
-- Tie important numbers to readable source metadata near relevant content.
-- Preserve source references for audit without cluttering the visible report.
-
-#### Visuals And Tables
-- Report visual headers should be neutral (chart name + short description). Put insights in adjacent narrative.
-- Every visualization needs an adjacent explanatory paragraph.
-- Report trend charts need enough data to make shape worth reading.
-- Tables default to spacious density for narrative reports.
-
-#### Metrics And Language
-- Describe metrics in plain English before implementation details.
-- Clarify definitions, cohorts, denominators before relying on a metric.
-- Put raw numbers in context: percent of base, comparison to baseline, or historical range.
-- Use shorthand large numbers in narrative (`899k`, `10.9k`, `1.2M`).
-
----
-
-## Part B: Dashboard Building
-
-Build source-backed analytical dashboards that help teams monitor performance, explore drivers, and act on metrics.
-
-### Workflow
-
-#### 1. Define The Dashboard Brief
-
-Understand who will use the dashboard, what they need to measure, which metrics matter, what surface it should live in, and constraints. Decide whether the dashboard is for status monitoring, recurring review, or analytical exploration.
-
-#### 2. Select The Delivery Surface
-
-- **BI tool**: default when connected BI is available (Tableau, Looker, Power BI, etc.)
-- **HTML dashboard**: portable static dashboard for sharing
-- **Streamlit**: when user explicitly asks or existing Streamlit app needs changes
-- **Interactive web**: JavaScript-based with ECharts/Chart.js for custom needs
-
-#### 3. Gather And Validate The Data
-
-- Find the source path before rendering.
-- Validate data trust (source, grain, freshness, reconciliation).
-- Resolve time and context anchors.
-- Stop if source-backed data is unavailable (no mock dashboards unless explicitly requested).
-
-#### 4. Define The Metric Model
-
-Select metrics and classify the measurement object:
-- **Reach**: who/what is using the product, penetration, activation, coverage.
-- **Volume**: events, usage, transactions, sessions, throughput, frequency.
-- **Value**: revenue, cost, margin, savings, conversion, retention value.
-- **Quality**: success/failure rates, reliability, latency, satisfaction.
-- **Depth**: repeat usage, intensity, feature mix, workflow completion.
-- **Mix**: segment, geography, channel, product/version, plan, cohort.
-- **Movement**: trend, growth, seasonality, pre/post, benchmark, forecast.
-- **Risk**: data coverage, freshness, known blind spots, capacity.
-
-Map into dashboard roles: hero metrics (default view), diagnostic metrics (movement/breakdowns), guardrails, and detail metrics (lookup).
-
-#### 5. Design The Dashboard Layout
-
-Arrange summary to detail: key status/KPI first → movement over time → breakdowns → detail tables. Use global filters only when they materially update the view. Keep dashboards visual-heavy and neutral.
-
-#### 6. Choose The Right Charts
-
-Use the data-visualization skill for chart selection and encoding. Choose the simplest visual that answers the viewer's question.
-
-#### 7. Build And Validate
-
-Build in the selected surface. Before handoff check: opens cleanly, filters work, charts render, numbers reconcile, performance acceptable.
-
-### Dashboard Quality Bar
-
-- Default view answers the primary audience question before interaction.
-- Filters are few, meaningful, and work correctly.
-- Cards, charts, and tables reconcile.
-- Metric set covers relevant families with primary outcomes, drivers, guardrails.
-- Source freshness and caveats are visible where they matter.
-
----
-
-## Part C: Product & Business Analysis
-
-Answer product or business questions with data-backed evidence, context, and a recommendation.
-
-### Workflow
-
-#### 1. Start From The Decision
-
-Identify the decision, audience, and action the analysis should inform:
-- The question and decision to inform
-- Who will use the answer and what they can act on
-- The scope and comparison that define a useful answer
-- The outcome or behavior that matters
-- Any assumptions needed to proceed
-
-#### 2. Gather Decision-Relevant Context
-
-Before deeper analysis, clarify:
-- **Intent**: what the work was meant to accomplish
-- **Definitions**: how the metric/source is defined and measured
-- **Timing**: what changed around the analysis period
-- **Constraints**: decisions or limitations affecting realistic action
-
-#### 3. Frame The Analysis
-
-Turn the question into a focused analytical framework:
-- Specific data questions that would support or change the recommendation
-- Comparisons and dimensions to inspect
-- Unit of analysis matching the decision
-- Metric definitions and caveats
-
-#### 4. Run Focused Quantitative Analysis
-
-- Follow the framework. Run analyses that could change the recommendation first.
-- Use the right comparison. Do not conclude a group is best just because it has the most total usage—normalize, check growth, check behavior.
-- Size the opportunities. Estimate magnitude of impact.
-- Keep work inspectable. Record queries and analysis.
-- Validate before concluding.
-
-#### 5. Translate Evidence Into Decision Implications
-
-Interpret evidence through decision lenses (choose relevant ones):
-- **Current scale**: large enough to matter?
-- **Momentum**: growing, shrinking, accelerating?
-- **Breadth**: broad-based or narrow?
-- **Concentration**: depends on few large entities?
-- **Intensity**: deep enough per unit?
-- **Efficiency**: better output for input required?
-- **Addressability**: can the team act on this?
-- **Differentiation**: requires distinct motion?
-- **Risk/dependency**: constraints that change recommendation?
-
-#### 6. Hand Off The Recommendation
-
-Make the recommendation explicit:
-- What they should believe or do next
-- Why the evidence supports that
-- Which caveats or dependencies matter
-- What follow-up would improve confidence

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