brasil-cli-analyst

name: brasil-cli-analyst description: Use this skill whenever the task needs to answer a question about Brazil with local official microdata — PNADC trimestral, PNADC anual visita 5, Censo 2022, TSE eleitorado, IPCA, or salário mínimo — using the brasil / pnad CLI. Trigger for any state-level income analysis, household income-band distribution, annual income-source composition (labor vs benefits vs pensions vs capital), dashboard snapshot, SQLite query, or when a journalist / analyst / LLM agent needs a read-mostly, statistically auditable answer grounded in the repo's local outputs instead of writing ad-hoc pandas code.

brasil-cli-analyst

Use the local brasil CLI (alias pnad) as the primary interface to Brazilian official microdata in this repository. It produces labeled CSVs, SQLite tables, a rich terminal dashboard, and machine-readable JSON payloads with bootstrap confidence intervals on every estimate.

when to trigger this skill

• The user asks about Brazilian income, poverty, inequality, demographics, regional comparison, benefits, pensions, informal work, or PNADC microdata.
• The user wants a state-by-state (UF) or macro-region breakdown.
• The user wants a faixa de salário mínimo cut (0-2, 2-5, 5-10, 10+ SM).
• The user wants an annual decomposition of income into work / benefits / previdência / capital.
• The user needs 95% confidence intervals (bootstrap over IBGE replicate weights).
• The user wants a local, reproducible answer — no network calls required once data is synced.
• The answer will feed a narrative, briefing, dashboard, or report.

when NOT to trigger this skill

• The user wants to analyze a dataset not in this repo (POF, Censo Demográfico microdata, RAIS, CAGED).
• The user wants real-time market data, news, or web research — use a WebSearch or a dedicated finance tool.
• The user just wants to read the existing docs/artigo_pt.md or docs/index.html — no CLI call needed.

decision tree — pick the right subcommand

                         ┌─────────────────────────────────────┐
                         │  user question about Brazilian data │
                         └──────────────┬──────────────────────┘
                                        │
                      ┌─────────────────┴──────────────────┐
                      │                                    │
           broad / interpretive?                  precise / custom cut?
           ("paint me a picture")                 ("exact number for X")
                      │                                    │
                      ▼                                    ▼
       ┌─────────────────────────┐             ┌──────────────────────────┐
       │  brasil dashboard       │             │   is it a faixa de SM    │
       │  --format json          │             │      distribution?       │
       └─────────┬───────────────┘             └──────────┬───────────────┘
                 │                                        │
                 ▼                                        ▼
    need benefits/pensions split?                  YES           NO
           │                                         │            │
         YES     NO                                  ▼            ▼
           │     │                  ┌────────────────────┐  ┌────────────────┐
           ▼     ▼                  │ brasil             │  │ brasil query   │
    --mode anual \            dashboard default         │ renda-por-faixa-sm │  │ --sql "..."    │
    --composition-by-band \   (tri + anual)              │ --format json      │  │ --db ...sqlite │
    --dependency-ranking                                 │ --group-by uf|pais │  └────────────────┘
                                                        └────────────────────┘

One-line rule of thumb:

canonical workflow

1. Check artifacts first. Before running anything heavy, verify that data/outputs/brasil.sqlite and data/outputs/base_*_labeled_npv.csv already exist. Do NOT re-run pipelines unless artifacts are missing or obviously stale.

2. Inspect schema with PRAGMA table_info(...) before writing SQL. Column names are verbose (VD5001__rendim_domiciliar), and casual guessing causes silent mismatches.

3. Prefer JSON output for anything that will be consumed by another agent or a dashboard. Human-formatted tables are harder to parse.

4. Pass through CI fields (*_moe, *_ci_low, *_ci_high) whenever you report a number — never strip them. Auditability is the point.

5. Cite the weight column and vintage. Every claim should be traceable to a specific weight (V1028 / V1032), a specific target month (IPCA deflator), and a specific SM reference.

the three primary subcommands in detail

brasil dashboard

A rich nation + UF + macro-region summary with CI, Lorenz, bands, cross-tabs, age pyramid, and (in annual mode) income-source composition. Best first command when you don't yet know what you're looking for.

# auto-discover and combine trimestral + anual when both are built
brasil dashboard

# annual, with the premium breakdowns
brasil dashboard \
  --mode anual \
  --composition-by-band \
  --dependency-ranking \
  --format json

Annual-mode payload includes:

• income_composition_national — national breakdown by source
• composition_by_band — per-faixa breakdown by source
• uf_dependency_ranking — state ranking by (benefits + previdência) share
• income_lenses_national — total income / excluding benefits / excluding transfers / labor-only

brasil renda-por-faixa-sm

Explicit band distribution with per-group CI. Use when the user wants the exact shape of the distribution.

brasil renda-por-faixa-sm \
  --input data/outputs/base_labeled_npv.csv \
  --group-by uf \
  --uf-order renda_desc \
  --format json

brasil query

Arbitrary read-only SQL. Use when the other two can't express the cut.

brasil query \
  --db data/outputs/brasil.sqlite \
  --sql "SELECT UF_label AS uf, \
                AVG(VD5001__rendim_domiciliar) AS avg_brl, \
                COUNT(DISTINCT dom_id) AS households \
         FROM base_anual_labeled_npv \
         GROUP BY 1 ORDER BY 2 DESC LIMIT 5"

Do NOT claim CI from arbitrary SQL — query does not compute bootstrap variance.

eight example questions → exact CLI

annual income lenses

When the user wants a "with vs without benefits" sensitivity, the annual dashboard exposes these lenses in income_lenses_national and income_lenses_by_band:

Typical usage: compare renda_total.gini vs somente_trabalho.gini to quantify how much redistribution the state is actually doing.

methodology cheat sheet

• Quarterly labor income: VD4020 (effective), fallback VD4019 (habitual).
• Annual household income: VD5001, plus 8 source columns (V5001A2..V5008A2) and 4 composition lenses.
• Household aggregation: dom_id = f"{Ano}{Trimestre}{UPA}{V1008}".
• Weights:
  • Quarterly primary: V1028__peso_com_calibracao (fallback V1027).
  • Annual primary: V1032__peso_com_calibracao (fallback V1031).
• Replicate weights for CI: V1028001..V1028200 (trimestral) or V1032001..V1032200 (anual). 200 replicates → bootstrap variance.
• Deflator: IPCA monthly index; target month defaults to the latest IPCA month, override with --target YYYY-MM.
• SM reference: BCB series 1619 (nominal monthly minimum wage).

safety & guardrails

• brasil query is read-only by default. Writes require --allow-write.
• Default SQL parser rejects multi-statement queries.
• Claim uncertainty only when you computed it — do not attach a fabricated ± X margin to a query result.
• When reporting a number publicly, include:
  • weight column actually used
  • replicate count actually found
  • IPCA target month
  • SM reference month
  • rows / households that entered the estimate
• Anything under --unweighted is diagnostic only, never publication.

troubleshooting

related skill

• pnad-query — thin sibling skill specialized in ad-hoc SQL with a column dictionary and the 10 most common safe queries pre-written.

references in this skill

• references/cli-cookbook.md — extended CLI patterns and SQL recipes.
• examples/prompts.md — end-to-end LLM prompts that produce good results.