Skill Tracer
Skills › Scientific Agent Skills › market-research-reports › FORMATTING_GUIDE.md

FORMATTING_GUIDE.md

166 lines · skills/market-research-reports/assets/FORMATTING_GUIDE.md at 5f2bc03

Open on GitHub
1# Market Report Formatting Guide
2
3Use formatting to expose evidence quality and uncertainty, not to make estimates
4look more certain. The bundled LaTeX files are optional; Markdown, HTML, DOCX, or
5another user-requested format is equally acceptable.
6

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.

Raw lines 1 to 6
7## Information hierarchy
8
9Use the following order within each analytical section:
111. finding or question;
122. evidence and exact claim IDs;
133. calculation or interpretation;
144. assumptions and uncertainty;
155. implication or decision threshold.
17Keep these statement types visually and verbally distinct:
19- **Observed fact** — directly represented by cited evidence.
20- **Estimate** — a source's or analyst's uncertain estimate.
21- **Calculation** — deterministic result from listed inputs and formula.
22- **Scenario** — conditional result, not a prediction or confidence interval.
23- **Recommendation** — judgment based on findings and stated objectives.

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.
Raw lines 7 to 24
25## Required labels for quantitative content
27Every quantitative table, figure, callout, or headline metric should show:
29- geography and coverage;
30- period or as-of date;
31- currency and base year when monetary;
32- nominal, real, current-price, constant-price, or chained basis;
33- stock, flow, count, share, rate, price, or index;
34- unit and denominator;
35- taxonomy and version when classifications define scope;
36- historical versus forecast status;
37- source IDs and calculation ID;
38- revision status and material limitations.
40Do not combine differently defined values in one visual scale. Normalize them
41first and retain the conversion record.

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.

Raw lines 25 to 42
43## Color and accessibility
45The style uses a restrained, colorblind-aware palette:
47- navy: structure and observed evidence;
48- teal: calculated values;
49- amber: assumptions or uncertainty;
50- red: limitations or unresolved conflicts;
51- gray: context and unavailable evidence.
53Never rely on color alone. Add labels, symbols, line styles, or direct
54annotations. Check grayscale legibility and reading order.

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.

Raw lines 43 to 55
56## LaTeX usage
58Place `market_research.sty` next to the report and use:
60```latex
61\documentclass[11pt]{report}
62\usepackage{market_research}
63```
65Compile from that directory with a TeX Live or MiKTeX installation containing
66`fontspec`, TeX Gyre Heros, and the packages required by the style. Use XeLaTeX or
67LuaLaTeX; the Unicode font setup does not target pdfLaTeX. Run twice for the contents:
69```bash
70xelatex -no-shell-escape -halt-on-error -interaction=nonstopmode market_report_template.tex
71xelatex -no-shell-escape -halt-on-error -interaction=nonstopmode market_report_template.tex
72```
74The template and snippets contain placeholders and synthetic examples, not current
75market findings. Inspect every rendered page for clipping, table overflow, font
76substitution, and unresolved references. Bracketed placeholder text after `\item`
77must be braced (`\item {[Finding]}`); otherwise LaTeX treats it as the list label.
79The package provides:
81```latex
82\begin{evidencebox}[Observed evidence]
83Claim C-014 maps to sources S-003 and S-011.
84\end{evidencebox}
86\begin{calculationbox}[Calculation CALC-007]
87Top-down and bottom-up estimates differ by 12.4\% of their midpoint.
88\end{calculationbox}
90\begin{assumptionbox}[Scenario assumptions]
91The upside case assumes faster adoption; it is not assigned a probability.
92\end{assumptionbox}
94\begin{limitationbox}[Material limitation]
95The source series was revised after the original retrieval date.
96\end{limitationbox}
97```
99The compatibility aliases `keyinsightbox`, `marketdatabox`, `riskbox`,
100`recommendationbox`, and `calloutbox` remain available for existing reports,
101but prefer the evidence-specific environments above.

LaTeX usage

Place market_research.sty next to the report and use:

\documentclass[11pt]{report}
\usepackage{market_research}

Compile from that directory with a TeX Live or MiKTeX installation containing fontspec, TeX Gyre Heros, and the packages required by the style. Use XeLaTeX or LuaLaTeX; the Unicode font setup does not target pdfLaTeX. Run twice for the contents:

xelatex -no-shell-escape -halt-on-error -interaction=nonstopmode market_report_template.tex
xelatex -no-shell-escape -halt-on-error -interaction=nonstopmode market_report_template.tex

The template and snippets contain placeholders and synthetic examples, not current market findings. Inspect every rendered page for clipping, table overflow, font substitution, and unresolved references. Bracketed placeholder text after \item must be braced (\item {[Finding]}); otherwise LaTeX treats it as the list label.

The package provides:

\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.

Raw lines 56 to 102
103## Tables
105Put units in column headers and scope in the caption. Do not mix percentages and
106currency on a single unlabelled axis.
108```latex
109\begin{table}[htbp]
110\centering
111\caption{Conditional market-size scenarios, Exampleland, nominal 2025 USD/year}
112\begin{tabular}{@{}lrrrl@{}}
113\toprule
114Scenario & TAM & SAM & SOM & Evidence \\
115\midrule
116Downside & [value] & [value] & [value] & S-001; S-004 \\
117Base & [value] & [value] & [value] & S-001; S-004 \\
118Upside & [value] & [value] & [value] & S-001; S-004 \\
119\bottomrule
120\end{tabular}
121\end{table}
122```
124Use `unknown` rather than a zero when evidence is missing. Explain suppression,
125rounding, residual categories, and totals that do not add because of chain
126weighting or independent seasonal adjustment.

Tables

Put units in column headers and scope in the caption. Do not mix percentages and currency on a single unlabelled axis.

\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.

Raw lines 103 to 127
128## Optional figures
130Figures are optional and should be created only when they improve
131understanding. A figure caption must identify:
133```latex
134\caption{Scenario range by year. USD/year at current prices; Exampleland;
135historical through 2025 and conditional scenarios thereafter.
136Sources: S-001, S-004. Calculation: CALC-FCST-002.}
137```
139Never use decorative imagery as evidence. Never infer market share from logo
140size, search rank, or an unlabelled generated graphic.
141For nominal forecasts, the historical anchor year is not a constant-price base:
142label each year's current-price currency. Use "constant 2025 USD" only after an
143explicit inflation adjustment.

Optional figures

Figures are optional and should be created only when they improve understanding. A figure caption must identify:

\caption{Scenario range by year. USD/year at current prices; 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. For nominal forecasts, the historical anchor year is not a constant-price base: label each year's current-price currency. Use "constant 2025 USD" only after an explicit inflation adjustment.

Raw lines 128 to 144
145## Citations
147Use stable source IDs in the report body and a complete evidence ledger in the
148appendix. A suggested compact notation is:
150```text
151The published count increased after the latest revision [C-014; S-003].
152```
154The bibliography entry alone is not enough: the claims ledger must map each
155claim to the exact source record, retrieval date, and applicable calculation or
156assumption IDs.

Citations

Use stable source IDs in the report body and a complete evidence ledger in the appendix. A suggested compact notation is:

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.

Raw lines 145 to 157
158## Final checks
160- No placeholder numbers or unsupported precision remain.
161- Forecasts and TAM/SAM/SOM are visibly labeled as scenarios.
162- Observed and forecast periods are visually separated.
163- All monetary content states currency, base year, and price basis.
164- Every table and optional figure has source and calculation IDs.
165- Unknowns, conflicts, revisions, and limitations are visible.
166- Layout does not imply endorsement, legal advice, or investment advice.

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.
Raw lines 158 to 166