@monoes/monomindcli 2.15.3 → 2.15.4

package/org-skills/market-research-reports/assets/FORMATTING_GUIDE.md

@@ -0,0 +1,149 @@
+# Market Report Formatting Guide
+
+Use formatting to expose evidence quality and uncertainty, not to make estimates
+look more certain. The bundled LaTeX files are optional; Markdown, HTML, DOCX, or
+another user-requested format is equally acceptable.
+
+## Information hierarchy
+
+Use the following order within each analytical section:
+
+1. finding or question;
+2. evidence and exact claim IDs;
+3. calculation or interpretation;
+4. assumptions and uncertainty;
+5. implication or decision threshold.
+
+Keep these statement types visually and verbally distinct:
+
+- **Observed fact** — directly represented by cited evidence.
+- **Estimate** — a source's or analyst's uncertain estimate.
+- **Calculation** — deterministic result from listed inputs and formula.
+- **Scenario** — conditional result, not a prediction or confidence interval.
+- **Recommendation** — judgment based on findings and stated objectives.
+
+## Required labels for quantitative content
+
+Every quantitative table, figure, callout, or headline metric should show:
+
+- geography and coverage;
+- period or as-of date;
+- currency and base year when monetary;
+- nominal, real, current-price, constant-price, or chained basis;
+- stock, flow, count, share, rate, price, or index;
+- unit and denominator;
+- taxonomy and version when classifications define scope;
+- historical versus forecast status;
+- source IDs and calculation ID;
+- revision status and material limitations.
+
+Do not combine differently defined values in one visual scale. Normalize them
+first and retain the conversion record.
+
+## Color and accessibility
+
+The style uses a restrained, colorblind-aware palette:
+
+- navy: structure and observed evidence;
+- teal: calculated values;
+- amber: assumptions or uncertainty;
+- red: limitations or unresolved conflicts;
+- gray: context and unavailable evidence.
+
+Never rely on color alone. Add labels, symbols, line styles, or direct
+annotations. Check grayscale legibility and reading order.
+
+## LaTeX usage
+
+Place `market_research.sty` next to the report and use:
+
+```latex
+\documentclass[11pt]{report}
+\usepackage{market_research}
+```
+
+The package provides:
+
+```latex
+\begin{evidencebox}[Observed evidence]
+Claim C-014 maps to sources S-003 and S-011.
+\end{evidencebox}
+
+\begin{calculationbox}[Calculation CALC-007]
+Top-down and bottom-up estimates differ by 12.4\% of their midpoint.
+\end{calculationbox}
+
+\begin{assumptionbox}[Scenario assumptions]
+The upside case assumes faster adoption; it is not assigned a probability.
+\end{assumptionbox}
+
+\begin{limitationbox}[Material limitation]
+The source series was revised after the original retrieval date.
+\end{limitationbox}
+```
+
+The compatibility aliases `keyinsightbox`, `marketdatabox`, `riskbox`,
+`recommendationbox`, and `calloutbox` remain available for existing reports,
+but prefer the evidence-specific environments above.
+
+## Tables
+
+Put units in column headers and scope in the caption. Do not mix percentages and
+currency on a single unlabelled axis.
+
+```latex
+\begin{table}[htbp]
+\centering
+\caption{Conditional market-size scenarios, Exampleland, nominal 2025 USD/year}
+\begin{tabular}{@{}lrrrl@{}}
+\toprule
+Scenario & TAM & SAM & SOM & Evidence \\
+\midrule
+Downside & [value] & [value] & [value] & S-001; S-004 \\
+Base     & [value] & [value] & [value] & S-001; S-004 \\
+Upside   & [value] & [value] & [value] & S-001; S-004 \\
+\bottomrule
+\end{tabular}
+\end{table}
+```
+
+Use `unknown` rather than a zero when evidence is missing. Explain suppression,
+rounding, residual categories, and totals that do not add because of chain
+weighting or independent seasonal adjustment.
+
+## Optional figures
+
+Figures are optional and should be created only when they improve
+understanding. A figure caption must identify:
+
+```latex
+\caption{Scenario range by year. Nominal 2025 USD/year; Exampleland;
+historical through 2025 and conditional scenarios thereafter.
+Sources: S-001, S-004. Calculation: CALC-FCST-002.}
+```
+
+Never use decorative imagery as evidence. Never infer market share from logo
+size, search rank, or an unlabelled generated graphic.
+
+## Citations
+
+Use stable source IDs in the report body and a complete evidence ledger in the
+appendix. A suggested compact notation is:
+
+```text
+The published count increased after the latest revision [C-014; S-003].
+```
+
+The bibliography entry alone is not enough: the claims ledger must map each
+claim to the exact source record, retrieval date, and applicable calculation or
+assumption IDs.
+
+## Final checks
+
+- No placeholder numbers or unsupported precision remain.
+- Forecasts and TAM/SAM/SOM are visibly labeled as scenarios.
+- Observed and forecast periods are visually separated.
+- All monetary content states currency, base year, and price basis.
+- Every table and optional figure has source and calculation IDs.
+- Unknowns, conflicts, revisions, and limitations are visible.
+- Layout does not imply endorsement, legal advice, or investment advice.

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

@@ -0,0 +1,290 @@
+# 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/org-skills/market-research-reports/references/evidence_model.md

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