Skip to main content
skill CX Codex

econometric-diagnostics — Claude Code skill: VAR checks

econometric-diagnostics is a Claude Code skill that checks VAR/BVAR residuals and model adequacy after estimation or on request to test autocorrelation, heteroskedasticity, normality, or structural breaks.

Apache-2.0 ★ 89 updated 2026-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bis-med-it/marco-BIS --skill econometric-diagnostics -a claude-code
Open on GitHub

What econometric-diagnostics does

The skill checks VAR/BVAR residuals and reports model diagnostics. Its built-in tests include Ljung–Box, Jarque–Bera, and ARCH-LM for each equation, a stability measure based on the largest eigenvalue modulus, and lag selection comparisons using AIC, BIC, and HQ.

Extra checks, such as Granger causality and CUSUM, run separately when called for. Their results and recommendations go into the research log; the standard report table contains a reduced set of fields. Economic anomalies such as wrongly signed responses belong to the next stage, not this statistical check.

A non-stationary or unstable label near a unit root does not automatically reject a model: level systems with shrinkage priors can show this pattern. The skill calls for a separate review of responses and disclosure of the classification.

What it helps with

  • test VAR equation residuals for autocorrelation
  • detect conditional heteroskedasticity with ARCH-LM
  • check equation residuals for normality
  • compare lag choices under AIC, BIC, and HQ
  • assess system stability using eigenvalues

Example prompts for the agent

  • Check VAR residuals for autocorrelation, heteroskedasticity, and normality.
  • Assess model stability and compare the lag choices from AIC, BIC, and HQ.
  • Run residual diagnostics and test the model for structural breaks.

How to install econometric-diagnostics

1Skills CLI (Vercel)

npx skills add bis-med-it/marco-BIS --skill econometric-diagnostics -a claude-code

2Manually: put the files in place

~/.claude/skills/diagnostics/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/diagnostics/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about econometric-diagnostics

How do I install econometric-diagnostics in Claude Code?

Run npx skills add bis-med-it/marco-BIS --skill econometric-diagnostics -a claude-code. The skill file is at ~/.claude/skills/diagnostics/SKILL.md.

What does econometric-diagnostics do?

It checks VAR/BVAR residuals and system stability, then compares lag-order selections. Extra tests can be run separately.

How does the skill assess stability in a VAR in levels?

A root near one in a level system is not an automatic reason to reject the model. The response dynamics should be assessed separately, and the stability classification disclosed.

Source text

SKILL.md · Apache-2.0
---
name: econometric-diagnostics
description: >
  Residual diagnostics and model adequacy checks for VAR/BVAR models. Use when the
  orchestrator reaches the diagnostics step of Stage 4 (estimation), whose results
  feed the Stage 5 sensibility check, or when the user asks to check residuals,
  test for autocorrelation, heteroskedasticity, normality, or structural breaks.
---

# Econometric diagnostics

## Tests performed

**Built-in bundle.** `lib.diagnostics(fit)` provides:

- per equation: Ljung-Box (one or more lags), Jarque-Bera and ARCH-LM;
- system level: the maximum companion-matrix eigenvalue modulus, with a
  status label (stability);
- an AIC/BIC/HQ lag-order comparison: it refits an OLS VAR at
  p = 1..`max_lag_search` and reports which p each criterion picks.

The other tests below are marked *additional*. They are not part of the
built-in bundle; the agent can run them separately (e.g. via statsmodels)
when the question calls for them.

### Residual-level diagnostics

For each equation in the VAR system:

1. **Autocorrelation.** Ljung-Box test at lags 4, 8, 12 (quarterly) or 6, 12, 24 (monthly).
   (`lib.diagnostics(fit, lb_lags=[...])` computes all requested lags in one
   call; the report's diagnostics table labels each row with the lag actually
   used.) *Additional:* Breusch-Godfrey LM test for the system.
2. **Heteroskedasticity.** ARCH-LM test (Engle, 1982) to detect conditional
   heteroskedasticity. *Additional:* White test for unconditional
   heteroskedasticity.
3. **Normality.** Jarque-Bera test per equation. *Additional:*
   Lomnicki-Jarque-Bera for the system.
   Note: non-normality is common in macro data and is not a reason to reject the model
   unless extreme.

### System-level diagnostics

1. **Stability.** Companion matrix eigenvalues. Report the maximum root and classify the dynamics as stationary (below 1),
   unit-root (at 1 within sampling error) or explosive (above 1). Apply the
   declared model-class and replication criteria consistently, treat
   near-unit-root sampling uncertainty as a disclosed diagnostic, and do not
   certify stability from finite-horizon plots.
   (`lib.diagnostics` reports the maximum modulus; plotting the eigenvalues
   on the unit circle diagram is an additional step.)
   **Arbitration for LEVELS systems:** `lib.diagnostics` labels any
   max |eig| ≥ 1.0 "non-stationary / unstable", but a VAR in log-levels
   (or with a random-walk Minnesota prior) legitimately sits at or just
   above the unit circle; several canonical replications validate
   against an expected band like 1.0 ± 0.05. Reconcile in this order:
   (i) does the spec intend unit-root-like persistence (levels +
   shrinkage)? then near-1 is expected, not a failure; (ii) apply the
   Stage-5 standard for the IRFs: responses to transitory shocks should
   die out and responses to permanent shocks flatten to a finite limit;
   growth at long horizons is a failure signal, but a flat-looking response
   within a finite horizon does not show that a root above one is stable;
   (iii) treat the lib label as a prompt to run checks (i)-(ii) and to
   disclose the classification, never as an auto-reject or an auto-pass.
2. **Lag-order comparison.** AIC, BIC and HQ picks across p = 1..`max_lag_search`
   (built in; a pick that differs from the fitted p is listed in the warnings).
3. **Granger causality** (*additional*). Wald tests for block exogeneity.
   Useful for interpreting the system structure.
4. **Lag exclusion** (*additional*). Joint significance of each lag across all equations.
5. **Set-identified models: acceptance rate.** For sign/zero-restriction
   schemes, track accepted draws / attempts against the canonical run or
   the entry's expected range (the Uhlig replication validates ~0.06 ±
   0.04). Low acceptance or a missed `target_accepted` quota is a
   computational and precision warning. Acceptance depends on the number of
   variables, the restrictions, the proposal measure and the sampler, so
   compare like with like, inspect the accepted and effective draw counts,
   and check stability separately. Do not infer invalid restrictions from a
   universal acceptance threshold, and do not silently report results from
   too few accepted draws.

### Structural break detection (optional, additional)

1. CUSUM and CUSUM-of-squares tests.
2. If the sample is long, consider a split-sample stability check at known break dates
   (e.g., 1979Q4 for Volcker, 2008Q3 for GFC).

**Scope note: statistical vs economic anomalies.** This skill covers the
statistical gate. *Economic* anomalies (price puzzle, wrong-signed
responses, implausible magnitudes) are Stage-5 territory: the remedy
ladder lives in `skills/specification/SKILL.md` §"Iterative revision after
failed sensibility checks". Go there, not here, when the numbers are
statistically clean but economically wrong.

## Output format

**For the research log**, record `lib.diagnostics(...).to_log_dict()`, plus
any additional tests run separately and the agent's recommendation:

```
diagnostics:
  residuals:                                  # keyed by variable name
    M1:
      ljung_box: {4: {stat, p_value}, 8: ..., 12: ...}   # keyed by lag
      jarque_bera_stat, jarque_bera_pvalue
      arch_stat, arch_pvalue
      breusch_godfrey: {stat, p_value}        # additional; only if run separately
  stability: {max_eigenvalue_modulus, stable: bool, status}   # status: stationary | marginal (near unit root) | non-stationary / unstable
  lag_selection: {current_p, max_lag_search, aic_recommended, bic_recommended, hqic_recommended}
  portmanteau: {stat, p_value, lags}          # additional; only if run separately
  eigenvalues: list of complex numbers        # additional; only if run separately
  warnings:                                   # lib.diagnostics(...).warnings
    - "Autocorrelation detected in M1 equation at lag 4 (p=0.02)"
    - "ARCH effects in GNP deflator equation"
  recommendation: "Consider increasing lag order or adding conditional heteroskedasticity"   # written by the agent; not a lib field
```

**For the report**, do not build the table by hand.
`VARReport.add_standard_sections` passes the fit's `DiagnosticReport`
through the report layer's adapter (`_build_diagnostics_dict_from_report`
in `scripts/lib/report.py`). A direct call to `VARReport.add_diagnostics`
takes a reduced view, keyed by variable name with numeric Ljung-Box lags:

```yaml
per_equation:
  M1:
    ljung_box:
      4: {p_value: 0.30}
      8: {p_value: 0.40}
    arch_lm: {p_value: 0.50}
    jarque_bera: {p_value: 0.60}
system:
  stability:
    max_eigenvalue_modulus: 0.90
    note: stationary
```

Additional tests, warnings and recommendations stay in the log; the report
table shows only these fields.

## Propose → confirm (handing back to Stage 5 / Stage 4)

When presenting results to the user, lead with whether the model passes or
fails in plain language. Diagnostics never silently re-specifies the model. On a **critical** failure
(instability, or severe autocorrelation indicating misspecification):

1. **State the failed test in plain language** and why it matters economically,
   e.g. "the companion matrix has a root at 1.02, so the VAR is explosive and
   impulse responses won't die out."
2. **Propose one specific remedy with rationale**, drawn from the usual levers
   (+1 lag, reorder / add a variable, tighten the prior, shorten the sample),
   e.g. "I propose adding a 5th lag; the Ljung-Box failure at lag 4 points to
   unmodelled own dynamics."
3. **Wait for the user to confirm or override** before routing back to Stage 4
   for re-estimation. (The orchestrator's 5-iteration automatic budget covers
   only implementation/data-error fixes and pre-specified statistical rules;
   economically substantive revisions like this one are each gated.)

For **soft** warnings (mild non-normality, marginal ARCH), state them and
recommend proceeding; don't block. Either way the flag and its disposition are
logged via the research-log skill. Never auto-respecify without surfacing the
choice. This is design principle 3 (active suggestion, human confirmation)
applied to diagnostics.

© bis-med-it · Apache-2.0 · bis-med-it/marco-BIS

Similar skills

SKILL.md skills catalog →

From the same set12

The whole set →
consistency-audit The consistency-audit Claude Code skill checks a framework’s skills, library code, and dictionary for consistency. Run it on demand, before a release, or after a batch of edits. CX Codex +1 ★ 89repo stars advisor-protocol The advisor-protocol Claude Code skill sends difficult mathematical reasoning to a more capable model for review. It activates when an agent is unsure how to interpret a derivation or translate it into code. CX Codex +1 ★ 89repo stars model-selection The model-selection Claude Code skill matches econometric models to a research question and available data. It runs when a user needs an approach or wants to check a model they have chosen. CX Codex +1 ★ 89repo stars research-log The research-log Claude Code skill records decisions and stages in an econometric analysis. It runs after another MaRCo@BIS skill finishes a stage or when asked for an audit trail, reproducibility log, or session summary. CX Codex +1 ★ 89repo stars knowledge-base The knowledge-base Claude Code skill helps an agent weigh general econometric knowledge against country-specific data and conventions. It activates when setting up an analysis or working with local sources and research. CX Codex +1 ★ 89repo stars model-dictionary The model-dictionary Claude Code skill searches a literature-based dictionary of econometric specifications. It joins model selection and requests to examine a paper for a new entry. CX Codex +1 ★ 89repo stars benchmarking The benchmarking Claude Code skill evaluates forecast performance and checks estimation results. Run it after a model fit or while preparing results for a paper. CX Codex +1 ★ 89repo stars results-presentation results-presentation — a Claude Code skill that turns econometric results into charts, tables, and written interpretation. It activates at the reporting stage or when results need to be presented or prepared for publication. CX Codex +1 ★ 89repo stars

Project sponsors

Companies that keep this analytics open