@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/market-research-reports/references/data_analysis_patterns.md

@@ -1,290 +0,0 @@
-# Data Analysis Patterns for Market Research
-
-## Measurement contract
-
-Define the quantity before collecting numbers:
-
-- product/service inclusion and exclusion;
-- buyer, user, payer, and transaction type;
-- geography and treatment of imports/exports;
-- historical period, forecast horizon, and as-of date;
-- revenue, expenditure, gross output, value added, units, capacity, users, or
-  another measure;
-- stock versus flow;
-- gross versus net, taxes included/excluded, and channel level;
-- currency, exchange-rate convention, base year, and nominal/real basis;
-- industry and product taxonomy with version;
-- denominator ID used in every share or rate.
-
-If two estimates do not share this contract, they are not directly comparable.
-
-## TAM, SAM, and SOM
-
-Treat all three as conditional scenario constructs.
-
-### Definitions
-
-- **TAM**: value or volume of all in-scope demand under the stated market
-  definition and time basis.
-- **SAM**: subset of TAM serviceable under explicit product, geography,
-  regulatory, channel, capacity, and customer constraints.
-- **SOM**: subset of SAM obtainable within a stated time horizon under explicit
-  competitive, operational, sales, retention, and capacity assumptions.
-
-Never present SOM as a guaranteed share or TAM as an objective universal truth.
-
-### Top-down method
-
-Use disjoint components:
-
-```text
-TAM_top = sum(value_i * in_scope_fraction_i)
-```
-
-Each component needs a unique coverage key, source IDs, period, unit, and
-denominator. Do not apply a broad percentage to an unrelated aggregate merely
-because the resulting number looks plausible.
-
-### Bottom-up method
-
-For a recurring-use market:
-
-```text
-component_i =
-    customer_count_i
-  * addressable_fraction_i
-  * annual_quantity_per_customer_i
-  * price_per_unit_i
-
-TAM_bottom = sum(component_i)
-```
-
-Alternative physical-capacity models may use installed base, utilization,
-replacement cycle, throughput, or transactions. Keep dimensions explicit so
-the resulting unit can be checked.
-
-### SAM and SOM
-
-```text
-SAM_s = TAM * serviceable_fraction_s
-SOM_s = SAM_s * obtainable_share_s
-```
-
-The fractions belong to scenario `s`. At minimum, use distinct downside and
-upside cases; a base case is usually useful. For each case, list assumptions,
-evidence, constraints, and horizon. Do not assign probabilities without a
-validated probabilistic model.
-
-### Preventing double counting
-
-Common failures:
-
-- adding manufacturer revenue to distributor or end-customer spend;
-- adding domestic production, imports, and sales without subtracting exports,
-  inventories, or overlapping channels;
-- summing parent and subsidiary revenue;
-- adding product bundles and their included components;
-- combining gross output and value added;
-- counting the same establishment in multiple segment labels;
-- adding annual transactions to installed-base stock;
-- applying overlapping geography or customer filters independently.
-
-Controls:
-
-1. assign a unique coverage key to every component;
-2. use mutually exclusive, collectively understood segments;
-3. define a single denominator ID;
-4. draw money and product flows through the value chain;
-5. reconcile supply, use, trade, inventory, and channel margins;
-6. show an ``unallocated/unknown'' residual rather than forcing totals;
-7. test the sum against an independent control total.
-
-Supply-use tables distinguish products from industries and the origin/use of
-goods and services. Use the
-[OECD Supply and Use Tables](https://www.oecd.org/en/data/datasets/supply-and-use-tables.html)
-and national accounts methodology when the value chain spans intermediate and
-final demand.
-
-### Reconciliation
-
-Keep methods separate:
-
-```text
-absolute_gap = abs(TAM_top - TAM_bottom)
-midpoint = (TAM_top + TAM_bottom) / 2
-gap_percent = absolute_gap / midpoint
-```
-
-Investigate gaps in this order:
-
-1. definition and denominator;
-2. geography, period, currency, and price basis;
-3. taxonomy and segment concordance;
-4. gross/net, taxes, channel margins, imports/exports;
-5. missing or duplicate coverage;
-6. source revision and sample limitations;
-7. price, volume, penetration, and utilization assumptions.
-
-Do not average the methods until their scopes are demonstrably compatible. If
-uncertainty remains, report both or retain a range.
-
-## Growth and forecasts
-
-### Historical growth
-
-```text
-YoY_t = value_t / value_(t-1) - 1
-CAGR = (end / start)^(1 / periods) - 1
-```
-
-CAGR compresses the path. Always show start/end values and period count. It is
-undefined when the start is nonpositive and can hide volatility, breaks, and
-revisions.
-
-### Scenario forecast
-
-```text
-value_(t+1,s) = value_(t,s) * (1 + growth_rate_(t,s))
-```
-
-Build rate paths from named drivers rather than copying a paid headline
-forecast. Separate:
-
-- historical observed period;
-- nowcast or estimate period;
-- conditional forecast period.
-
-For each scenario, state demand, price, supply, regulation, competition,
-capacity, and timing assumptions. Use different paths, not merely different
-labels.
-
-### Sensitivity
-
-One-way sensitivity varies one input while holding others fixed. Report:
-
-- tested range and rationale;
-- resulting endpoints;
-- switching value where the decision changes;
-- nonlinearities or constraints;
-- interactions omitted by one-way analysis.
-
-Scenario analysis explores coherent joint states. It is not a confidence
-interval. Statistical prediction intervals require a specified model, error
-process, diagnostics, and coverage interpretation.
-
-The 2023
-[OMB Circular A-4](https://www.whitehouse.gov/wp-content/uploads/2023/11/CircularA-4.pdf)
-provides primary guidance on characterizing uncertainty, sensitivity, and
-transparent assumptions. The
-[UK Green Book 2026](https://www.gov.uk/government/publications/the-green-book-appraisal-and-evaluation-in-central-government/the-green-book-2026)
-provides additional public-sector appraisal guidance. Adapt principles
-proportionately; do not imply that a market report is a regulatory appraisal.
-
-## Units, currencies, and price bases
-
-### Nominal and real
-
-- **Nominal/current-price** values reflect prices in each period.
-- **Real/constant-price** values remove price change using an identified
-  deflator and base/reference year.
-- Never combine nominal and real values in one total or growth rate.
-- Match nominal values to nominal assumptions and real values to real
-  assumptions.
-
-Record:
-
-```text
-real_value_base_year = nominal_value_t * price_index_base / price_index_t
-```
-
-Identify the index, geography, category, vintage, and whether it is appropriate
-for the market. A broad CPI may be unsuitable for a specialized B2B input.
-
-### Chained measures
-
-Chained-dollar components may not add to published aggregates. BEA's
-[chained-dollar guidance](https://www.bea.gov/resources/methodologies/chained-dollar-indexes)
-explains why. Use published contributions to growth or current-dollar
-composition rather than forcing additivity.
-
-### Currency conversion
-
-Record:
-
-- source and target currency;
-- spot, period-average, or period-end convention;
-- rate date/period and source;
-- order of currency conversion and deflation;
-- effects of high inflation or multiple exchange-rate regimes.
-
-Do not mix converted flows using period-end rates with balances using averages
-without explanation.
-
-### Stock and flow
-
-A stock is measured at a point in time; a flow over an interval. Installed
-base, employees on a date, and capacity are stocks. Revenue, transactions, and
-shipments during a year are flows. A stock-to-flow conversion requires an
-explicit turnover, utilization, or replacement-cycle assumption.
-
-## Shares and concentration
-
-```text
-share_i = in_scope_measure_i / same_scope_total
-HHI = sum((100 * share_i)^2)
-CR4 = sum(four_largest_shares)
-```
-
-Before computing:
-
-- define product and geographic scope;
-- use one share metric and denominator;
-- include the same period and channel level;
-- account for unknown/residual firms;
-- disclose whether values are revenue, units, capacity, or active users;
-- avoid false precision when company and total estimates use different methods.
-
-The [2023 U.S. Merger Guidelines](https://www.ftc.gov/system/files/ftc_gov/pdf/2023_merger_guidelines_final_12.18.2023.pdf)
-describe HHI as one indicator in case-specific merger analysis. The
-[2024 EU Market Definition Notice](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=OJ:C_202401645)
-addresses product/geographic scope, non-price parameters, dynamic and digital
-markets, alternate share metrics, and evidence. A market report's HHI is
-descriptive and is not a legal conclusion.
-
-## Survey and interview synthesis
-
-### Survey estimate
-
-For a probability sample, report the design-based or model-based estimator,
-weights, design effect, and appropriate uncertainty. Do not infer population
-precision from sample size alone.
-
-For a non-probability sample, disclose recruitment and model assumptions. Use
-careful labels such as ``among respondents'' unless a validated adjustment
-supports broader inference.
-
-### Interview themes
-
-Use a structured coding frame:
-
-```text
-theme_id | definition | inclusion rule | exclusion rule |
-supporting excerpts | disconfirming excerpts | roles represented
-```
-
-Report a theme as qualitative evidence. Do not translate mention counts into
-market prevalence.
-
-## Confidence labels
-
-Confidence is an analyst assessment, not a substitute for uncertainty:
-
-- **High**: directly observed, well-defined primary evidence with compatible
-  scope and low material revision risk.
-- **Medium**: triangulated evidence with manageable assumptions or limitations.
-- **Low**: sparse, conflicting, indirect, modeled, or scope-mismatched evidence.
-- **Not assessed**: opinion or recommendation where an evidence-confidence
-  label is inappropriate.
-
-Always state the reasons. Multiple low-quality sources do not automatically
-produce high confidence.

package/skills/market-research-reports/references/evidence_model.md

@@ -1,148 +0,0 @@
-# Evidence Model and Citation Integrity
-
-This model makes a report auditable at claim level. A bibliography is necessary
-but insufficient: each material claim must map to the exact source records,
-calculation, and assumptions that support it.
-
-## Statement classes
-
-Label every material statement as one of:
-
-1. **Quantitative fact** — a value directly represented by a cited source.
-2. **Quantitative estimate** — a source's or analyst's uncertain estimate.
-3. **Qualitative fact** — an attributable event, policy, feature, or statement.
-4. **Calculation** — deterministic transformation of cited inputs.
-5. **Forecast** — conditional future path based on stated assumptions.
-6. **Opinion** — attributed respondent or analyst judgment.
-7. **Recommendation** — decision advice derived from findings and objectives.
-
-Do not rewrite an estimate as a fact, a scenario as a prediction, an interview
-theme as prevalence, or a recommendation as an evidence claim.
-
-## Source record
-
-Give each source a stable ID such as `S-001`. Record:
-
-- title, publisher/author, URL or persistent identifier;
-- source type and original data producer;
-- publication date and retrieval date;
-- archived local snapshot path, if legally permitted;
-- geography and covered population;
-- currency, base year, and nominal/real/current/constant/chained basis;
-- stock, flow, count, share, rate, price, index, or mixed measure;
-- unit and denominator;
-- industry/product taxonomy and version;
-- preliminary/revised/final/vintage/current status;
-- collection or estimation method;
-- survey frame, mode, sample, weighting, and response information when relevant;
-- limitations, suppression, imputation, breaks, and known revisions;
-- license, terms, and attribution requirements.
-
-For an aggregator, record both the delivery platform and original producer. For
-example, a FRED series should retain its original agency/source metadata; FRED
-availability does not erase third-party rights or methodology.
-
-## Claim record
-
-Give each claim a stable ID such as `C-014`. Record:
-
-- exact claim text;
-- statement class;
-- one or more source IDs;
-- report location;
-- as-of date and geography;
-- currency/base year/price basis, measure type, unit, and denominator;
-- taxonomy and version;
-- revision status;
-- calculation ID and assumption IDs where applicable;
-- a calibrated confidence label and reasons;
-- limitations or conflicts material to interpretation.
-
-One citation at the end of a paragraph does not automatically support every
-sentence in the paragraph. Split compound claims when different sources support
-different components.
-
-## Source hierarchy
-
-Use fitness for the claim, not prestige alone. A practical default:
-
-1. primary law, regulator decision, official filing, or official statistic;
-2. original company filing or attributable first-party operating disclosure;
-3. transparent survey or study with inspectable methods;
-4. peer-reviewed or institutional research using identifiable primary data;
-5. industry association data with disclosed coverage and methods;
-6. reputable secondary synthesis;
-7. paid market estimate with inspectable scope/method and lawful access;
-8. news or commentary for leads and attributable events, not unsupported size
-   estimates.
-
-The best source can differ by claim. A company filing is authoritative about
-reported company revenue but not automatically about total market size. An
-official industry total may be authoritative but too broad for the product
-market being studied.
-
-## Conflicting evidence
-
-Never choose the most convenient number silently.
-
-1. Compare definitions, period, geography, currency, price basis, unit,
-   denominator, taxonomy, sample, and revision vintage.
-2. Determine whether values are genuinely conflicting or merely different
-   measures.
-3. Prefer the source closest to the primary observation and fit to the claim.
-4. If both remain plausible, retain a range or parallel estimates.
-5. Document the conflict, decision rule, and sensitivity to the choice.
-6. Do not average incompatible estimates.
-
-## Revisions and vintages
-
-- Record retrieval date for every online source.
-- Record a dataset vintage or release identifier when available.
-- Preserve the original input snapshot or checksum when terms permit.
-- Mark preliminary data and expected revisions.
-- On refresh, compare new and prior values; do not overwrite silently.
-- Use archived/vintage systems where needed for reproducibility.
-- For sources that expose only the latest version, preserve the retrieved file
-  and state that historical versions are not supplied by the API.
-
-## Calculation lineage
-
-Each calculation record should identify:
-
-- formula and calculation ID;
-- exact input fields and source IDs;
-- exclusions and coverage keys;
-- conversions, exchange-rate source/date, and deflator/index;
-- rounding policy;
-- intermediate values;
-- output unit and denominator;
-- assumptions and sensitivity values;
-- software/script version or command used.
-
-Do not cite a calculated result as if it appeared verbatim in a source.
-
-## Source integrity failures to avoid
-
-- fabricated citations, URLs, access dates, quotes, or paid figures;
-- citing a search-result snippet instead of the underlying source;
-- citation laundering through an aggregator or secondary article;
-- using a source outside its geographic, temporal, or definitional scope;
-- omitting a correction, restatement, or revision;
-- attributing a denominator from one source to a numerator from another without
-  reconciliation;
-- claiming that multiple citations are independent when they reproduce one
-  underlying estimate;
-- treating absence of public evidence as evidence of absence.
-
-## Minimum audit
-
-Before release:
-
-1. validate the source ledger;
-2. audit every factual, estimate, calculation, and forecast claim;
-3. resolve missing source IDs;
-4. review unused sources and citation clusters;
-5. spot-check every headline number against the archived source;
-6. reproduce market-size and forecast outputs from local inputs;
-7. rerun unit/currency/base-year consistency checks;
-8. retain unresolved conflicts and limitations in the report.

package/skills/market-research-reports/references/methods_and_ethics.md

@@ -1,162 +0,0 @@
-# Research Methods, Privacy, and Ethics
-
-## Primary research decision
-
-Conduct interviews or surveys only when the research question cannot be
-answered adequately with existing lawful evidence. Define the purpose,
-population, data fields, retention period, and reporting plan before
-recruitment.
-
-Do not use research as disguised selling, lead generation, political
-campaigning, or a way to obtain confidential competitor information.
-Apply the current
-[AAPOR Code of Professional Ethics and Practices](https://aapor.org/standards-and-ethics/),
-revised in June 2026, alongside the disclosure standards below.
-
-## Survey evidence
-
-Follow the [AAPOR Disclosure Standards](https://aapor.org/standards-and-ethics/disclosure-standards/)
-for any survey claim. Record:
-
-- sponsor, funder, and fieldwork organization;
-- research objective and target population;
-- probability or non-probability design;
-- sampling frame, selection, recruitment, eligibility, and incentives;
-- mode, language, instrument, exact wording, ordering, and field dates;
-- unweighted sample sizes overall and for reported subgroups;
-- weighting variables, benchmark sources, trimming, calibration, and design
-  effects;
-- dispositions, response/cooperation/participation rates and definitions;
-- imputation, exclusions, attention checks, coding, and quality controls;
-- appropriate precision measure and assumptions;
-- coverage, nonresponse, measurement, processing, and model limitations.
-
-Do not:
-
-- report a conventional margin of sampling error for a non-probability sample
-  unless a defensible model and its assumptions are fully disclosed;
-- equate a large sample with representativeness;
-- describe opt-in respondents as a random sample;
-- compare waves after changing question wording, mode, population, or weighting
-  without analyzing the break;
-- report subgroup estimates with undisclosed small bases;
-- claim causality from a descriptive cross-sectional survey.
-
-The FCSM's
-[Best Practices for Nonresponse Bias Reporting](https://statspolicy.gov/assets/fcsm/files/docs/FCSM%20NRBA%20Report%20062623.pdf)
-supports reporting standard response rates and examining key subgroups. A high
-response rate does not by itself eliminate bias, and a lower rate does not by
-itself prove bias; analyze the mechanism and available benchmarks.
-
-## Interviews and focus groups
-
-Record:
-
-- recruitment criteria and source;
-- role categories represented and material gaps;
-- consent script, recording permission, incentive, and withdrawal process;
-- interview dates, mode, duration, moderator, and guide version;
-- coding method, number of coders, disagreements, and use of software;
-- whether themes were expected, emergent, divergent, or disconfirming;
-- limitations from purposive recruitment, sponsor effects, social desirability,
-  and nonresponse.
-
-Quotes require permission and de-identification appropriate to the context.
-Paraphrases must not change meaning. Never attach percentages or population
-prevalence to qualitative themes.
-
-## Privacy and data minimization
-
-Collect only data needed for the stated purpose. Before collection:
-
-1. identify applicable privacy, employment, recording, consumer, and research
-   rules in every jurisdiction;
-2. provide a clear notice and obtain appropriate consent;
-3. avoid sensitive data unless necessary, lawful, and specifically protected;
-4. separate contact details from research responses;
-5. define role-based access, encryption, retention, deletion, and incident
-   handling;
-6. assess re-identification risk from combinations of role, employer,
-   geography, quotes, and rare attributes;
-7. aggregate or suppress small groups;
-8. document any processor or platform and cross-border transfer.
-
-Never place names, email addresses, phone numbers, account identifiers, raw IP
-addresses, private messages, recordings, or other direct identifiers in the
-report evidence ledger. A source ID should identify a controlled record, not a
-person.
-
-The [ICO data minimisation guidance](https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/data-protection-principles/a-guide-to-the-data-protection-principles/data-minimisation)
-is a useful primary reference where UK GDPR applies. Apply the governing law in
-the actual jurisdiction rather than assuming one framework is universal.
-
-## Lawful customer and competitor research
-
-Permitted evidence may include public filings, regulator records, official
-registries, public product documentation, published pricing, lawful public
-procurement records, consented research, and licensed databases used within
-their terms.
-
-Do not:
-
-- impersonate a customer, employee, regulator, journalist, investor, or
-  prospective hire;
-- misstate identity or purpose to gain access;
-- evade authentication, access controls, paywalls, technical restrictions,
-  robots policies, or contractual limits;
-- solicit or accept trade secrets, source code, credentials, nonpublic pricing,
-  customer lists, roadmaps, bids, or confidential documents;
-- use leaked, stolen, inadvertently exposed, or unlawfully obtained material;
-- collect personal profiles unrelated to the research purpose;
-- infer protected or sensitive attributes;
-- contact employees in a manner that pressures them to breach duties;
-- turn absence of a public feature statement into a definitive ``no.''
-
-Use `unknown` when lawful public evidence is insufficient. Keep screenshots or
-snapshots only when terms allow, and record product edition, geography, account
-tier, and as-of date.
-
-## Competition and antitrust framing
-
-Competitive analysis is descriptive unless qualified counsel performs a legal
-assessment. The
-[2023 U.S. Merger Guidelines](https://www.ftc.gov/system/files/ftc_gov/pdf/2023_merger_guidelines_final_12.18.2023.pdf)
-and the
-[2024 European Commission Market Definition Notice](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=OJ:C_202401645)
-show why product/geographic market definition, shares, concentration, entry,
-dynamic competition, and evidence are case-specific.
-
-Rules:
-
-- do not equate a TAM category with a relevant antitrust market;
-- state the share denominator and why it reflects competitive reality;
-- test alternate product and geographic boundaries;
-- consider non-price competition, multi-sided platforms, zero-price services,
-  innovation, capacity, active users, imports, and prospective entry where
-  relevant;
-- report unknown participants and residual share;
-- treat HHI and concentration ratios as descriptive screening measures, not a
-  legal conclusion;
-- do not label a firm a monopoly, dominant, anticompetitive, or collusive
-  without appropriately sourced legal findings or qualified legal analysis.
-
-## Conflicts and sponsor influence
-
-Disclose the sponsor, funder, analyst role, material commercial interests, and
-constraints on publication. A sponsor may set the question but must not dictate
-the evidence, remove unfavorable results, or suppress material limitations.
-Keep a record of deviations from the analysis plan.
-
-## Decision-use boundary
-
-A market report may inform planning, but it does not guarantee outcomes and
-must not present itself as:
-
-- investment advice or a solicitation to transact;
-- legal, antitrust, tax, accounting, or regulatory advice;
-- a fairness opinion, valuation opinion, or assurance engagement;
-- confirmation that a market figure is true merely because it appears in a
-  paid report.
-
-For high-stakes decisions, obtain qualified domain, legal, financial, privacy,
-and statistical review as appropriate.