practitioner-heuristics

Files (2)

• SKILL.md
• backtesting-patterns.md · references/

SKILL.md (first lines)

# Practitioner Heuristic Overlay

This skill adds the second risk lens alongside ES. It does two things:

1. enforce hard gates before advisory discussion
2. provide the heuristic context needed to sequence corrective actions

It should not replace the quantitative engine. ES remains binding.

## Architecture

### Hard gates

These gates block action classes:

| Gate | Threshold | Action |
|------|-----------|--------|
| ES limit | ES(97.5%) > 2.5% | Block new risk additions |
| Illiquidity ceiling | T2+T3 illiquid > 25% NW | Block new illiquid commitments |
| Employer concentration | Employer-linked liquid > 15% | Block incremental employer-linked risk |

### Advisory layers

These shape posture and the corrective path:

- ruin scenarios
- barbell posture
- regime concentration
- market temperature
- concentrated-position valuation context

## Mapping Tables

### Liquidity tier classification

| Tier | Label | Examples |
|------|-------|---------|
| T0 | Cash / risk-free | USD, VMFXX, SPAXX, SWVXX, FDRXX, SHV, BIL, SGOV, USFR, TFLO |
| T1 | Daily liquid | VTI, VXUS, VOO, SPY, QQQ, BND, AGG, TLT, GLD, GLDM |
| T2 | Semi-liquid | REITs, BDCs, interval funds |
| T3 | Illiquid | PE, VC, real estate, private credit |

### Barbell classification

| Bucket | Label | Examples |
|--------|-------|----------|
| Hyper-safe | Risk-free floor | USD, CASH, money-market funds, T-bills |
| Convex | Tail protection | GLDM, GLD, IAU, CAOS, TLT, DBMF, KMLM, approved long-vol structures |
| Fragile middle | Linear / concave payoff | broad beta, PE, individual equities, most credit, most real estate |

### Convex instrument menu

Treat this as governed input to `market-intel-direct.rank_convex_candidates`, not as an auto-prescription list.

Approved ranking universe:

- `GLDM`, `IAU`
- `DBMF`, `KMLM`
- `CAOS`
- `TLT` when regime-appropriate
- `SPY` put-spread templates when options capability permits

Avoid:

- `VXX`, `VIXY`
- `TAIL`
- `CYA`
- buffer ETFs presented as convex substitutes

## Execution Workflow

### Step 1: Run hard gates first

#### ES gate

- If `portfolio-analytics.analyze_portfolio_risk` returns `status == "critical"` or the illiquid overlay pushes adjusted ES above `2.5%`, fail the gate.

#### Illiquidity gate

- Use `finance-graph.get_net_worth` plus Ghostfolio liquid net worth.
- If illiquid share of household net worth is above `25%`, fail the gate.

#### Employer concentration gate

- Use `equity_comp` accounts plus any same-ticker holdings elsewhere.
- If employer-linked liquid exposure exceeds `15%`, fail the gate.

When a hard gate fails, say so plainly before advisory layers.

### Step 2: Run advisory layers

#### Ruin scenario

- Run `portfolio-analytics.compute_ruin_scenario`
- Show the full stress table, not only one scenario

#### Barbell posture

- Run `portfolio-analytics.classify_barbell_buckets`
- Report:
  - hyper-safe %
  - convex %
  - fragile-middle %
  - safe gap
  - convex gap
  - fragile excess

When convex is short, feed the gap into `market-intel-direct.rank_convex_candidates`.

#### Regime map

- Use the regime table plus macro inputs from `market-intel-direct.get_fred_series`
- Flag material underexposure to key regimes

#### Market temperature

- Run `market-intel-direct.get_shiller_cape`
- Run `market-intel-direct.compute_market_temperature`
- Only present a full score when `status == "complete"`

From hvkshetry/StewardOS, MIT.

More from hvkshetry/StewardOS