Savvy Analyst Training
Guided handbook — how to read Savvy intelligence correctly. Mirrors SAVVY_ANALYST_HANDBOOK.md.
1 · Prime directive
Savvy is deterministic and evidence-first. It never fabricates: a layer with no evidence returns status: "BLOCKED" with a machine reason, and inferred facts are hard-capped at 0.50 confidence. Same inputs → byte-identical output.
Read every envelope in a fixed order: confidence → BLOCK reasons → layer scores → ROI.
2 · Confidence
Confidence is evidence-first, layer-specific, and capped. Inferred/pattern-matched facts never exceed 0.50; the ROI layer's rolled-up confidence never exceeds 0.80; overall envelope confidence is the weighted mean of the OK layers (BLOCKED layers are excluded, not scored as zero).
| Band | Meaning |
|---|---|
| ≥ 0.80 | Very strong (extracted, corroborated) |
| 0.70–0.79 | Strong |
| 0.60–0.69 | Moderate |
| 0.50–0.59 | Weak |
| < 0.50 | Inferred — a hypothesis, not a fact |
Rule: low confidence ≠ bad unit. It means less evidence. Weight it; don't discard it.
3 · BLOCK reasons
A BLOCK means "no evidence → no verdict" for that layer — a data gap, not a negative signal. Common reasons:
| Reason | Meaning |
|---|---|
| unknown_unit | Unit id doesn't resolve in this namespace (not ingested) |
| NO_CANONICAL_UNIT | Resolves but has no net_area / unit_type / bedrooms |
| missing_community | No community → can’t scope market (ROI) |
| missing_unit_type | No canonical unit type (ROI) |
| market_blocked | Market layer BLOCKED, so ROI can’t lean on it |
| missing_rent_yield | No rent-yield reading (no dataset + no rent.db/price) |
| missing_price_history | No appreciation series for this community/type |
| no_developer_for_unit | No developer id and none inferable |
| no_payment_data | No payment plan supplied (payment is caller-provided) |
Rule: never override a BLOCK. Supply the missing evidence (payment plan, market datasets, developer id) and the same unit will compute.
4 · The layers
- Truth — extracted canonical facts + verdict (A–E) + classification.
- Unit-type — canonical type; flags when area/bedrooms disagree.
- Developer intelligence — resolved developer + reliability (0–1) + risk profile.
- Fitout — a generated (not official) layout when eligible; labeled as such.
- View / GIS — composite (0–1) from orientation, view type, water/park proximity, road-noise, obstruction.
- Payment — validates a caller-supplied plan → fit + recommendation. BLOCKs with none.
- Audit — floorplan/claim authenticity (A–E) + consistency vs the canonical unit.
- Desirability — liveability blend (0–1, A–E) over the surviving layers.
- Market — community/type signals → alignment (goodness) + risk (ill).
- ROI — see §5.
5 · ROI (scenario-based, never advice)
Three A–E bands (A is best: highest yield, highest appreciation, lowest risk) and two scenarios:
- Cash ROI = 0.4·f(yield) + 0.4·f(appreciation) − 0.2·risk_magnitude. Higher risk lowers ROI.
- Payment-Plan ROI = cash ROI − 0.2·f(burden) − 0.2·payment_risk. Self-BLOCKs without a plan.
- Cycle: early → higher appreciation & risk · mid → balanced · late → lower appreciation & risk.
Bands: yield A ≥ 7% … E < 4%; appreciation A ≥ 6% … E < 0%; risk A ≤ 0.2 … E > 0.8.
6 · View / GIS
Composite (0–1) over five sub-scores: view type, exposure (orientation; N best in Dubai, SW worst), amenity (best of water/park proximity — a "what-vs-what" vector), noise (road width), obstruction (neighbour height; corner relief).
- View ≥ 0.85 → premium outlook
- Amenity ≥ 0.90 → strong proximity uplift
- Obstruction ≤ 0.40 → low blockage penalty
7 · Portfolio & Insights
Portfolios return six deterministic ranked slices; Insights adds analyst categories with per-unit justification. A unit only appears in a category when every field that category reads is present (else it's excluded and noted in block_reasons).
| Insight | Criteria |
|---|---|
| High ROI | ROI ≥ 0.65, yield ≥ B, appreciation ≥ B, risk ≤ C |
| High Appreciation | appreciation = A, cycle ∈ {early, mid}, developer ≥ 0.75 |
| Safest | risk ≤ B, developer ≥ 0.80, market risk ≤ 0.40, payment risk ≤ 0.40 |
| Best View | view ≥ 0.85, amenity ≥ 0.90, obstruction ≤ 0.40 |
| Best Developer | developer reliability ≥ 0.85 |
| Mispriced | ROI ≥ 0.60, alignment ≥ 0.80, yield > community median |
8 · Analyst workflow
- Run the portfolio (or a single unit).
- Check confidence.
- Check BLOCK reasons.
- Read ROI (bands + both scenarios + cycle).
- Read appreciation, view, developer reliability, market alignment.
- Read insights — triage with rankings, strategize with categories.
- Decide.
9 · Analyst rules
- Never override a BLOCK.
- Never treat low confidence as negative, or high confidence as advice.
- Always check developer reliability, market alignment, and cycle position.
- If a number surprises you, read its
justification/components— the engine shows its work.