@monoes/monomindcli 2.15.2 → 2.15.4

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

@@ -0,0 +1,162 @@
+# 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.

package/org-skills/market-research-reports/references/official_data_sources.md

@@ -0,0 +1,196 @@
+# Official Data and Filing Sources
+
+Verified against first-party guidance on 2026-07-23. API rules can change:
+recheck the linked terms and limits before automated or high-volume use. The
+bundled scripts do not call these services and do not require API keys.
+
+## Routing by claim
+
+Start with the original authority most fit for the claim:
+
+- company financials and risk disclosures: the jurisdiction's official filing
+  system, then the filed document;
+- establishment, employment, prices, production, trade, population, and GDP:
+  the responsible national statistical office or central bank;
+- rules, approvals, enforcement, licenses, and consultations: the responsible
+  regulator or official legal gazette;
+- cross-country indicators: the original national source when comparability is
+  not required; otherwise an international harmonized dataset with metadata;
+- classifications: the current official NAICS, NACE, ISIC, product, trade, or
+  sector taxonomy and its correspondence tables.
+
+Do not treat an aggregator as an independent corroborating source when it
+reproduces the same underlying series.
+
+## United States
+
+### SEC EDGAR and company filings
+
+- [SEC Developer Resources](https://www.sec.gov/about/developer-resources)
+  documents company submissions and extracted XBRL data APIs.
+- [Accessing EDGAR Data](https://www.sec.gov/search-filings/edgar-search-assistance/accessing-edgar-data)
+  requires a declared user agent and states a current maximum of 10 requests per
+  second across the user's machines. Download only what is needed.
+- EDGAR filings can be corrected or removed after acceptance. Record accession
+  number, form, filing date, reporting period, amendment status, exact table or
+  XBRL fact, units, and retrieval date.
+- Consolidated company revenue is not automatically market revenue. Remove
+  out-of-scope products/geographies and avoid summing parent/subsidiary or
+  channel/end-customer values twice.
+
+### U.S. Census Bureau
+
+- The [Census Data API User Guide](https://www.census.gov/data/developers/guidance/api-user-guide.html)
+  links data to a geographic boundary and a dataset vintage.
+- As revised 2026-05-14, the
+  [query-limits page](https://www.census.gov/data/developers/guidance/api-user-guide.Query_Limits.html)
+  permits up to 50 variables per query and requires a key for all data queries.
+  The [key page](https://www.census.gov/data/developers/guidance/api-user-guide.API_Key.html)
+  describes free registration. Never place a key in a report, source ledger, or
+  bundled script.
+- Use program-specific methodology, margins of error, universe, geography, and
+  vintage. ACS estimates, Population Estimates, and decennial counts are not
+  interchangeable.
+- The [2022 Economic Census methodology](https://www.census.gov/programs-surveys/economic-census/year/2022/technical-documentation/methodology.html)
+  defines the target population, sampling frame, exclusions, administrative
+  data, imputation, disclosure avoidance, and product collection.
+- The [NAICS site](https://www.census.gov/naics) identifies 2022 NAICS as the
+  current published structure while a 2027 revision process is underway. Store
+  the version used.
+
+### Bureau of Labor Statistics
+
+The [BLS API FAQ](https://www.bls.gov/developers/api_faqs.htm), last modified
+2023-08-30, documents:
+
+- registered v2: 500 queries/day, 50 series/query, 20 years/query;
+- unregistered v1: 25 queries/day, 25 series/query, 10 years/query;
+- both: 50 requests per 10 seconds;
+- v2 registration renewal at least annually;
+- v1 returns observations and footnotes without descriptive metadata.
+
+Record series ID, survey/program, seasonal adjustment, units, frequency,
+footnotes, publication date, and revision status. Consult the program's
+methodology and release calendar rather than relying on the API response alone.
+
+### Bureau of Economic Analysis
+
+The [BEA API User Guide](https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf),
+dated 2026-04-20, requires a registered UserID and documents three rolling
+per-minute limits:
+
+- 100 requests;
+- 100 MB retrieved;
+- 30 errors.
+
+BEA returns HTTP 429 and a `Retry-After` header when throttled. The guide warns
+that limits may change. Query metadata methods before data, restrict years and
+dimensions, and avoid broad `ALL` requests. Record current versus chained
+dollars, reference year, table/line code, frequency, seasonality, and release
+vintage. Chained-dollar components may not be additive; use published
+contributions or current-dollar shares where appropriate.
+
+### Federal Reserve and FRED/ALFRED
+
+- [FRED API documentation](https://fred.stlouisfed.org/docs/api/fred/) describes
+  v2 bulk release history and v1 series-level FRED/ALFRED access.
+- A registered key is required under the
+  [FRED API Terms](https://fred.stlouisfed.org/docs/api/terms_of_use.html).
+  The reviewed terms do not state one fixed numerical request ceiling; they
+  reserve the right to impose or change limits.
+- The terms warn that third parties may own series and impose additional
+  restrictions. Follow the original producer's rights and attribution.
+- FRED normally presents latest values; ALFRED preserves real-time vintages.
+  Record source, release, series ID, frequency, units, seasonal adjustment,
+  notes, and vintage dates.
+
+## International and harmonized sources
+
+### World Bank
+
+The [Indicators API documentation](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation)
+states that v2 is current, v1 is discontinued, and API authentication is not
+required. Preserve indicator code, database/source, source note, source
+organization, unit, income/region classification vintage, and retrieval date.
+The [WDI catalog](https://datacatalog.worldbank.org/search/dataset/0037712/world-development-indicators)
+publishes metadata and revision-history resources. A World Bank indicator may
+originate with a national agency or another international organization; retain
+that lineage.
+
+### International Monetary Fund
+
+The [IMF Data API page](https://data.imf.org/en/Resource-Pages/IMF-API) states
+that IMF data are available through SDMX 2.1 and SDMX 3.0 APIs. Use the
+dataset's data structure, codelists, unit, scale, frequency, observation status,
+and methodological metadata. Do not assume similarly named indicators across
+IMF datasets have identical definitions.
+
+### OECD
+
+The [OECD Data Explorer API guide](https://www.oecd.org/en/data/insights/data-explainers/2024/09/api.html),
+published 2025-04-30, describes the SDMX API, free access subject to OECD terms,
+and rate limiting without publishing one universal numerical ceiling on that
+page. It warns that omitting a dataflow version selects the latest version and
+that later structures may not be backward compatible. Store agency, dataset,
+dataflow version, dimensions, codes, attributes, and query.
+
+### Eurostat
+
+The [Eurostat API introduction](https://ec.europa.eu/eurostat/web/user-guides/data-browser/api-data-access/api-introduction)
+documents Statistics, SDMX 2.1, SDMX 3.0, catalogue, and asynchronous services.
+It states that datasets are updated twice daily when changes are available and
+that the database contains only the latest version, without past-version
+documentation. Preserve the retrieved file and update timestamp when a
+reproducible vintage matters.
+
+The [ESS quality and metadata handbook](https://ec.europa.eu/eurostat/web/products-manuals-and-guidelines/-/ks-gq-21-021)
+is a standard for reporting source, process, quality, and metadata. Record flags,
+breaks, seasonal adjustment, units, NUTS/geography version, and dataset code.
+
+### Other national statistical agencies
+
+Use the relevant country's official agency before secondary compilations.
+Examples of current first-party interfaces:
+
+- [Statistics Canada Web Data Service](https://www.statcan.gc.ca/en/developers/wds/user-guide)
+  provides data and metadata. Guide revision 1.6 (2025-01-24) documents a
+  50-request/second server limit and 25-request/second individual IP limit, and
+  possible HTTP 409 responses during update windows.
+- The [UK ONS Developer Hub](https://developer.ons.gov.uk/) describes an open,
+  no-key beta API. It warns that breaking changes can occur; store dataset,
+  edition, and version because new versions reflect corrections, revisions, or
+  new data.
+
+For any country, confirm:
+
+1. the official statistics producer and legal mandate;
+2. release calendar, methodology, quality statement, and revision policy;
+3. classification and geography versions;
+4. API/download terms and current operational limits;
+5. whether the dataset is official, experimental, modeled, or an administrative
+   extract.
+
+## Industry and product classifications
+
+- [NAICS](https://www.census.gov/naics) classifies establishments by primary
+  economic activity; it is not itself a product-market definition.
+- [NACE Rev. 2.1](https://ec.europa.eu/eurostat/web/products-eurostat-news/w/wdn-20250624-1)
+  began feeding European statistics from 2025. Use the 2025 manual and
+  correspondence tables when comparing Rev. 2 and Rev. 2.1.
+- Product classifications (NAPCS, CPA, PRODCOM, CPC, HS/CN) may fit market
+  outputs better than an establishment-based industry code.
+- A concordance can be one-to-many or many-to-many. Never apply it as a
+  lossless conversion without weights and uncertainty.
+
+## API handling rules
+
+- Use APIs only during research, with user-approved network access.
+- Keep credentials outside reports and scripts; never commit keys.
+- Respect official terms, user-agent requirements, rate limits, retries, and
+  bulk-download guidance.
+- Cache lawful downloads, record the exact query and retrieval time, and avoid
+  repeatedly requesting unchanged data.
+- Validate response status, metadata, units, flags, suppression, and missing
+  values before analysis.
+- Treat current limits in this file as a dated snapshot, not a permanent
+  entitlement.

package/org-skills/market-research-reports/references/report_structure_guide.md

@@ -0,0 +1,283 @@
+# Market Research Report Structure
+
+Match the report to the decision and available evidence. There is no required
+page count, chapter count, figure count, or output format. Omit irrelevant
+modules and expand methods/limitations when uncertainty is high.
+
+## Front matter
+
+### Title and scope
+
+Include:
+
+- market and geography;
+- historical and forecast periods;
+- retrieval cutoff;
+- report version and classification;
+- sponsor, author, and material conflicts;
+- explicit statement that the report is not investment, legal, or financial
+  advice.
+
+Do not use logos, layouts, or wording that imply affiliation with another firm.
+
+### Executive synopsis
+
+Write last. It should stand alone and contain:
+
+1. decision context;
+2. formal market boundary in one sentence;
+3. highest-confidence findings with claim IDs;
+4. top-down and bottom-up scenario range;
+5. forecast scenario range and principal sensitivity;
+6. material conflicts and limitations;
+7. implications or options clearly labeled as judgment.
+
+Never introduce a metric in the synopsis that is absent from the evidence and
+claims ledgers.
+
+## 1. Scope and definitions
+
+Define:
+
+- product/service inclusion and exclusion;
+- customer, payer, user, and transaction;
+- value-chain level;
+- geography, imports/exports, and channels;
+- time basis and as-of date;
+- measure, unit, and denominator;
+- stock/flow and gross/net treatment;
+- currency, base year, and nominal/real basis;
+- industry and product classifications with versions;
+- adjacent markets that are excluded.
+
+Explain alternate plausible definitions and why one was selected. An industry
+classification is not automatically a product market or an antitrust market.
+
+## 2. Evidence and methods
+
+Describe:
+
+- source hierarchy and search cutoff;
+- original data producers and aggregator lineage;
+- exact claim-source mapping;
+- archived snapshots and revision handling;
+- extraction, cleaning, joins, conversions, and calculations;
+- source conflicts and reconciliation rules;
+- confidence labels;
+- primary-research methods and privacy controls;
+- missing evidence and analysis deviations.
+
+Summarize the source ledger by source type and revision status. Do not inflate
+source count by counting mirrors or derivative articles as independent.
+
+## 3. Market size
+
+### Top-down
+
+Show:
+
+- control total and definition;
+- disjoint components and coverage keys;
+- in-scope fractions;
+- channel/tax/trade adjustments;
+- source IDs and limitations;
+- resulting TAM scenarios.
+
+### Bottom-up
+
+Show:
+
+- population or installed base;
+- customer segments;
+- annual units or transactions;
+- price/spend assumptions;
+- addressable fractions;
+- source and assumption IDs;
+- resulting TAM scenarios.
+
+### SAM and SOM
+
+For each scenario, state:
+
+- serviceability filters;
+- capture-share assumptions;
+- time horizon;
+- capacity, channel, sales-cycle, retention, and competition constraints;
+- source evidence and analyst assumptions.
+
+Present TAM/SAM/SOM as conditional scenarios. Do not select one estimate merely
+because it is the midpoint.
+
+### Reconciliation and sensitivity
+
+Report:
+
+- absolute and percentage gap between methods;
+- definition, denominator, and coverage-key comparison;
+- corrections for double counting;
+- remaining unexplained difference;
+- sensitivity to major counts, price, penetration, serviceability, and capture;
+- switching values that change a decision.
+
+## 4. Demand and customer evidence
+
+Separate:
+
+- official/administrative or transactional evidence;
+- published survey evidence;
+- original survey evidence;
+- interview/focus-group themes;
+- analyst interpretation.
+
+For survey claims, include population, frame, sample method, mode, dates,
+unweighted sample, weighting, response/participation, wording, precision, and
+limitations. For interviews, include recruitment, consent, roles, mode, dates,
+coding, divergent views, and limits to generalization.
+
+## 5. Market dynamics
+
+For each driver or inhibitor:
+
+- state the mechanism;
+- identify observed evidence versus assumption;
+- quantify only with a defensible calculation;
+- define time horizon and leading indicators;
+- include disconfirming evidence;
+- state how it changes a scenario input.
+
+Frameworks such as PESTLE or SWOT may organize questions but are not evidence.
+Use them only when useful, and do not force a fixed number of factors or scores.
+
+## 6. Competitive landscape
+
+### Scope
+
+Define the product and geographic basis from the customer perspective. Consider
+substitutability, non-price dimensions, channels, imports, digital/multi-sided
+features, innovation, and dynamic change where relevant.
+
+### Competitor set
+
+State inclusion rules. Distinguish:
+
+- current direct competitors;
+- adjacent/substitute providers;
+- potential entrants;
+- channel partners or suppliers;
+- unknown/private participants.
+
+### Feature and positioning evidence
+
+Use the validated matrix with product edition, geography, date, status, and
+source IDs. Publish scoring rules for any positioning map. Use `unknown` when
+evidence is absent.
+
+### Shares and concentration
+
+State numerator and denominator, metric, period, coverage, residual share, and
+alternate definitions. Treat HHI/CRn as descriptive screens. Do not make legal
+antitrust conclusions.
+
+## 7. Forecast scenarios
+
+### Historical basis
+
+Show series IDs, units, frequency, seasonal adjustment, revisions, taxonomy
+breaks, transformations, and vintage.
+
+### Scenario design
+
+For each named scenario, document:
+
+- annual rate path or driver equations;
+- demand, price, supply, regulation, competition, and capacity assumptions;
+- evidence and assumption IDs;
+- constraints and internal consistency;
+- conditions that would make the scenario obsolete.
+
+Do not assign probabilities without a defensible probabilistic model. Do not
+call scenario bounds confidence or prediction intervals.
+
+### Sensitivity
+
+Report endpoints under stated input shifts, rank influential assumptions, and
+identify decision thresholds. If interactions matter, add coherent combined
+scenarios rather than relying only on one-way sensitivity.
+
+## 8. Regulation and policy
+
+Use primary regulator and legal sources. Record:
+
+- jurisdiction and authority;
+- instrument or docket identifier;
+- publication, adoption, and effective dates;
+- enacted/proposed/stayed/repealed status;
+- affected products and entities;
+- evidence-backed market mechanism;
+- uncertainty and need for legal review.
+
+Do not present a policy proposal as effective law or compliance interpretation
+as legal advice.
+
+## 9. Risks, implications, and options
+
+Separate:
+
+- observed risk indicator;
+- likelihood judgment;
+- impact mechanism;
+- exposure and time horizon;
+- early-warning measure;
+- mitigation or option;
+- residual uncertainty.
+
+Tie recommendations to explicit objectives and findings. Include dependencies,
+trade-offs, owner, timing, and evidence that would trigger revision. A
+recommendation is judgment, not a sourced fact.
+
+## 10. Limitations
+
+Consolidate:
+
+- data gaps and source conflicts;
+- paid or inaccessible evidence not verified;
+- classification and scope mismatch;
+- currency/base-year and conversion limits;
+- stock/flow or denominator uncertainty;
+- revisions and historical breaks;
+- imputation, suppression, survey, and interview limitations;
+- competitor evidence gaps;
+- forecast/model uncertainty;
+- sponsor and analyst conflicts.
+
+## Appendices
+
+Include as needed:
+
+- source/evidence ledger;
+- claims ledger;
+- calculation and assumption register;
+- unit/currency/base-year conversion table;
+- market-sizing inputs and outputs;
+- forecast and sensitivity inputs and outputs;
+- competitor-feature matrix;
+- survey instrument and methodology disclosure;
+- interview guide and de-identified coding framework;
+- revision log;
+- machine-readable local files.
+
+## Release gate
+
+- Scope and denominator are explicit and consistent.
+- Every factual or quantitative claim maps to source IDs.
+- Calculations map to inputs and assumptions.
+- Publication/retrieval dates and revisions are recorded.
+- Monetary values identify currency, base year, and price basis.
+- Stock/flow, units, taxonomy, and denominator are explicit.
+- Top-down/bottom-up methods are reconciled without double counting.
+- TAM/SAM/SOM and forecasts are conditional scenarios with sensitivity.
+- Survey and interview evidence carries full method and privacy disclosures.
+- Competitor evidence is lawful, dated, and does not infer `no` from `unknown`.
+- Conflicts and limitations remain visible.
+- No unsupported paid-market figures, fabricated citations, PII, trade secrets,
+  deceptive collection, brand impersonation, or investment-advice framing.