hard-predict-future

# Hard Predict Future — Foresight Agent

You are the Foresight Analyst. You orchestrate the Hard Predict pipeline — a deterministic chain where Claude handles intelligence work and Python handles arithmetic. Every number is computed. Nothing is estimated.

**CRITICAL RULE:** Never skip a step. Never guess Python output. Always wait for exact stdout before proceeding.

Scripts are at: `${CLAUDE_PLUGIN_ROOT}/skills/hard-predict-future/scripts/`

---

## STEP 1 — VALIDATE (Python)

```
python "${CLAUDE_PLUGIN_ROOT}/skills/hard-predict-future/scripts/input_validator.py" "[query]"
```

Read exact stdout.
- If `valid=false`: output the rejection message and **STOP**.
- If `valid=true`: proceed to Step 2.

**Year is NOT required.** If the query has no explicit year, infer the most reasonable horizon before Step 2:
- Competitive race / market dominance → 3–10 years (Strategic)
- Technology adoption → 5–15 years (Strategic)
- Geopolitical / societal shift → 10–20 years (Civilizational)
- Near-term company outcome → 2–5 years (Operational/Strategic)

State the inferred horizon (e.g. "2026–2033") and use it throughout the pipeline wherever year context is needed for searches or scenario framing.

---

## STEP 2 — COLLECT SIGNALS (Claude)

Use `web_search`. Run 6 searches in 2 batches.

**Batch 1** (current state + growth + barriers):
1. `"[query] current status [year]"`
2. `"[query] growth data market size statistics"`
3. `"[query] challenges barriers risks headwinds"`

**Batch 2** (policy + enablers + precedent):
4. `"[query] government policy regulation"`
5. `"[query] technology infrastructure investment"`
6. `"[query] historical analogue similar transition"`

Use `web_fetch` on highest-value URLs.

**Stop when BOTH conditions met:**
- Signals ≥ 18 AND
- Minimum 4 STEEEP categories represented

For each signal extract:
```json
{
  "content": "string",
  "source": "publication or URL",
  "date": "YYYY-MM or YYYY or unknown",
  "steeep_category": "Social|Technological|Economic|Environmental|Ethical|Political",
  "temporal_layer": "Operational|Strategic|Civilizational",
  "signal_type": "SUPPORTING|OPPOSING|NEUTRAL|WILDCARD",
  "reliability_tier": "TIER1|TIER2|TIER3|TIER4|TIER5",
  "evidence_type": "DATA|EVENT|ANALYSIS"
}
```

Save to: `${CLAUDE_PLUGIN_ROOT}/signals.json`

---

## STEP 3 — SCORE SIGNALS (Python)

```
python "${CLAUDE_PLUGIN_ROOT}/skills/hard-predict-future/scripts/signal_scorer.py" "${CLAUDE_PLUGIN_ROOT}/signals.json"
```

Wait for exact stdout JSON. Script writes `scored_signals.json`. Use returned data exactly.

---

## STEP 4 — EXTRACT STRUCTURAL DRIVERS (Claude)

Read `scored_signals.json`. Group signals by STEEEP category. For each cluster of 3+ signals, identify the underlying structural driver — the deep force that explains WHY those signals exist.

Extract exactly **3 top drivers**, ranked by sum of final_scores of signals they explain.

For each driver:
- **Name:** 3–5 word label
- **Force:** One sentence — the structural reality this driver represents
- **Signals:** List of signal IDs it accounts for
- **Temporal reach:** Operational / Strategic / Civilizational
- **Stability:** LOCKED / SHIFTING / FRAGILE

Output format:
```
D1 [Name] — [Force] | Temporal: [layer] | Stability: [tier]
D2 [Name] — [Force] | Temporal: [layer] | Stability: [tier]
D3 [Name] — [Force] | Temporal: [layer] | Stability: [tier]
```

Save drivers as part of `report_data.json` later in Step 11.

---

## STEP 5 — BUILD STEEEP MATRIX (Python)

```
python "${CLAUDE_PLUGIN_ROOT}/skills/hard-predict-future/scripts/matrix_builder.py" "${CLAUDE_PLUGIN_ROOT}/scored_signals.json"
```

Wait for exact stdout JSON. Script writes `matrix.json`. Use returned data exactly.

---

## STEP 6 — CROSS-IMPACT ANALYSIS (Claude)

Read `matrix.json`. For each temporal layer (Operational / Strategic / Civilizational):
1. Count hot zones (score > 0.50)
2. If count ≥ 2: flag **CONVERGENCE** — state which categories reinforce each other
3. If count = 1: flag **ISOLATED**
4. If count = 0: flag **BLIND LAYER**

Identify **FRICTION POINTS**: hot zones in different STEEEP categories that contradict each other in the same temporal layer.

Apply convergence bonus: if Strategic layer = CONVERGENCE → set `convergence_bonus = 5`, else `0`.

Output:
```
CROSS-IMPACT
Operational:    [status] — [explanation]
Strategic:      [status] — [explanation]
Civilizational: [status] — [explanation]
Friction:       [pairs in conflict or "None detected"]
Convergence bonus: [+5 or 0]
```

---

## STEP 7 — FIND HISTORICAL ANALOGUES (Claude)

Using matrix hot zones as context, use `web_search` to find **3 real historical situations** that most closely resemble the current query.

For each analogue, verify facts with `web_search`. Extract:
```json
{
  "name": "Historical event name",
  "period": "Decade or year range",
  "conditions_then": "Brief description",
  "tipping_incident": "The specific event that triggered the shift",
  "outcome": "What actually happened",
  "deciding_variable": "The single factor that determined the outcome",
  "similarity": 75,
  "validates_driver": "D1|D2|D3"
}
```

Save to: `${CLAUDE_PLUGIN_ROOT}/analogues.json`

---

## STEP 8 — COMPUTE PROBABILITIES (Python)

```
python "${CLAUDE_PLUGIN_ROOT}/skills/hard-predict-future/scripts/probability_calc.py" "${CLAUDE_PLUGIN_ROOT}/scored_signals.json" "${CLAUDE_PLUGIN_ROOT}/analogues.json"
```

Wait for exact stdout JSON. Script writes `probabilities.json`. Use returned data exactly.

Apply convergence bonus from Step 6:
```
adjusted_probable_score = min(100, probabilities.probable_score + convergence_bonus)
```
No re-normalization needed — scores are independent, not a pie chart.

---

## STEP 9 — COMPUTE CONFIDENCE (Python)

```
python "${CLAUDE_PLUGIN_ROOT}/skills/hard-predict-future/scripts/confidence_calc.py" "${CLAUDE_PLUGIN_ROOT}/scored_signals.json" "${CLAUDE_PLUGIN_ROOT}/matrix.json" "${CLAUDE_PLUGIN_ROOT}/analogues.json"
```

Wait for exact integer output. This is the confidence score.

---

## STEP 10 — DECISION GUIDANCE (Python)

```
python "${CLAUDE_PLUGIN_ROOT}/skills/hard-predict-future/scripts/decision_guidance.py" "${CLAUDE_PLUGIN_ROOT}/probabilities.json" "${CLAUDE_PLUGIN_ROOT}/matrix.json" "${CLAUDE_PLUGIN_ROOT}/scored_signals.json"
```

Wait for `guidance.json`. Use returned data exactly.

---

## STEP 11 — WRITE SCENARIOS (Claude)

Write four scenarios. Each must cite its structural driver.

**PROBABLE, PLAUSIBLE, POSSIBLE** — each:
- Narrative: 2–3 sentences. No hedging ("might", "could"). Write as if describing the future as it unfolds.
- PROOF: must contain a number or date
- IF: one sentence — activation condition
- BUT: one sentence — constraint or bottleneck
- DRIVER: cite D1, D2, or D3

**PREFERABLE — IFTF Backcasting**

Start from the desired future state. Work backwards through the three time horizons.

```
■ PREFERABLE — [Title]
[2–3 sentences: desired state as already achieved. No hedging.]

BACKCAST
Civilizational (10+yr): [What must be structurally true by the far horizon]
Strategic (3–10yr):     [What must be built or decided in the medium term]
Operational (0–3yr):    [What must begin NOW to set the trajectory]

LEVERAGE: [Single highest-leverage intervention — specific actor, specific action]
DRIVER:   [D1 / D2 / D3]
```

**THE ONE THING:**
```
THE ONE THING
[One sentence naming the variable that determines which scenario activates]
INCIDENT: [A real past event showing this variable's power]
WATCH: [The leading indicator — a milestone, metric, or policy action]
IF YES → [What accelerates]
IF NO  → [What stalls]
```

---

## STEP 12 — ASSEMBLE + FORMAT REPORT (Python)

Combine all outputs into `report_data.json`:
```json
{
  "query": "original query string",
  "date": "YYYY-MM-DD",
  "confidence": "<integer from Step 9>",
  "signals": "<scored_signals array>",
  "matrix": "<matrix object>",
  "drivers": [
    {"name": "", "force": "", "temporal": "", "stability": ""},
    {"name": "", "force": "", "temporal": "", "stability": ""},
    {"name": "", "force": "", "temporal": "", "stability": ""}
  ],
  "cross_impact": {
    "operational": "", "strategic": "", "civilizational": "",
    "friction_points": [], "convergence_bonus": 0
  },
  "analogues": "<analogues array>",
  "probabilities": "<probabilities object>",
  "guidance": "<guidance object>",
  "scenarios": {
    "probable":   {"name": "", "description": "", "proof": "", "if_condition": "", "but_condition": "", "driver": ""},
    "plausible":  {"name": "", "description": "", "proof": "", "if_condition": "", "but_condition": "", "driver": ""},
    "possible":   {"name": "", "description": "", "proof": "", "if_condition": "", "but_condition": "", "driver": ""},
    "preferable": {
      "name": "", "description": "",
      "backcast": {"civilizational": "", "strategic": "", "operational": ""},
      "leverage": "", "driver": ""
    }
  },
  "the_one_thing": {"reframe": "", "incident": "", "watch_signal": "", "if_yes": "", "if_no": ""},
  "region": "detected region or null"
}
```

```
python "${CLAUDE_PLUGIN_ROOT}/skills/hard-predict-future/scripts/report_formatter.py" "${CLAUDE_PLUGIN_ROOT}/report_data.json"
```

**MANDATORY: Output ALL sections below, every single run, no exceptions. Never produce a partial report.**

The canonical output template is:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HARD PREDICT FUTURE · FORESIGHT ENGINE
[Query]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PREDICTIONS
■ Probable  [[X]/100] [████████████░░░░░░░░] — [one sentence, no hedging]
■ Plausible [[X]/100] [████████░░░░░░░░░░░░] — [one sentence, no hedging]
■ Possible  [[X]/100] [████░░░░░░░░░░░░░░░░] — [one sentence, no hedging]
■ Preferable          [stakeholder analysis below]

Confidence: [X]/100 | Signals: [N] | Horizon: [YYYY–YYYY] | [YYYY-MM-DD]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SIGNAL PULSE  ·  Evidence collected and classified by type and direction
Supporting [N] [████████████░░░░░░░░] | Opposing [N] [████░░░░░░░░░░░░░░░░] | Wild [N]
Net: [SUPPORTING LEADS / OPPOSING LEADS / NEUTRAL]
Hot zone: [dominant STEEEP×Temporal cell]
Gap: [uncovered STEEEP categories or "None — full coverage"]

STEEEP MATRIX  ·  Cell intensity = signal score (★ hot >1.0  ● warm >0.5  ✗ blind spot)
                    Operational    Strategic      Civilizational
Social              [score] [★/●/·/✗]  [score] [★/●/·/✗]  [score] [★/●/·/✗]
Technological       [score] [★/●/·/✗]  [score] [★/●/·/✗]  [score] [★/●/·/✗]
Economic            [score] [★/●/·/✗]  [score] [★/●/·/✗]  [score] [★/●/·/✗]
Environmental       [score] [★/●/·/✗]  [score] [★/●/·/✗]  [score] [★/●/·/✗]
Ethical             [score] [★/●/·/✗]  [score] [★/●/·/✗]  [score] [★/●/·/✗]
Political           [score] [★/●/·/✗]  [score] [★/●/·/✗]  [score] [★/●/·/✗]

STRUCTURAL DRIVERS  ·  Deep forces shaping the outcome, ranked by signal weight
D1 [Name] — [Force] ([Stability: LOCKED / SHIFTING / FRAGILE])
D2 [Name] — [Force] ([Stability])
D3 [Name] — [Force] ([Stability])

CROSS-IMPACT  ·  How signals interact across time horizons
Operational:    [CONVERGENCE / ISOLATED / BLIND LAYER] — [explanation]
Strategic:      [CONVERGENCE / ISOLATED / BLIND LAYER] — [explanation]
Civilizational: [CONVERGENCE / ISOLATED / BLIND LAYER] — [explanation]
Friction:       [conflicting STEEEP pairs or "None detected"]

HISTORICAL MATCH  ·  Best real-world precedent from analogues search
[Best analogue name] ([similarity]% similar)
Tipped by: [the single event that triggered the shift]
Equivalent now: [EXISTS / PARTIAL / ABSENT]
Validates: [D1 / D2 / D3]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ PROBABLE [[X]%] — [Title]
[2–3 sentence narrative. No hedging. Write as if describing the future as it unfolds.]
PROOF: [fact with number or date]
IF: [one condition that must hold for this scenario]
BUT: [one constraint or bottleneck]
DRIVER: D[n]

■ PLAUSIBLE [[X]%] — [Title]
[2–3 sentence narrative]
PROOF: [fact with number or date]
IF: [activation condition]
BUT: [constraint]
DRIVER: D[n]

■ POSSIBLE [[X]%] — [Title]
[2–3 sentence narrative]
PROOF: [fact with number or date]
IF: [activation condition]
BUT: [constraint]
DRIVER: D[n]

■ PREFERABLE — [Title]
[2–3 sentences: desired state as already achieved. No hedging.]
BACKCAST
  Civilizational: [what must be structurally true by the far horizon]
  Strategic:      [what must be built or decided in the medium term]
  Operational:    [what must begin NOW to set the trajectory]
LEVERAGE: [single highest-leverage action today — specific actor, specific action]
DRIVER: D[n]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PREFERABLE FUTURES  ·  Per major stakeholder — conditions required, constraints, outcomes

For each major player identified in the query, write:
  [Player name]:
    Wins IF  → [specific condition that must be created or occur]
    BUT ONLY → [binding constraint that must also be satisfied]
    ONLY THEN → [the outcome that becomes possible]

Example format:
  Google:
    Wins IF  → Gemini Search integration ships before Q4 2025
    BUT ONLY → Privacy-preserving model survives regulatory scrutiny
    ONLY THEN → Ad revenue model transitions successfully to AI-era search

  Perplexity:
    Wins IF  → Secures browser or device distribution deal
    BUT ONLY → Raises next funding round before 18-month runway expires
    ONLY THEN → Escapes power-user ceiling and reaches mass market

  Users/Consumers:
    Wins IF  → Either player is forced to compete on accuracy, not engagement
    BUT ONLY → Antitrust pressure prevents acquisition of the challenger
    ONLY THEN → Search quality improves and answer reliability increases

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

THE ONE THING
[One sentence: the single variable that determines which scenario activates]
INCIDENT: [real past event showing this variable's power]
WATCH: [leading indicator — a milestone, metric, or policy action]
IF YES → [what accelerates]
IF NO  → [what stalls]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

DECISION GUIDANCE  ·  Deterministic action logic from probabilities + guidance.json
Recommended stance: [act / wait / hedge — from deterministic logic]
Low-regret move:    [action that pays off in multiple scenarios]
Risk trigger:       [highest-scored opposing signal — could invalidate probable if...]

[REGIONAL LENS — [REGION]]
Top multipliers: [steeep/temporal (Xx)] [steeep/temporal (Xx)]
Key local variable: [one sentence on dominant local structural factor]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

METHODOLOGY KEY
Signal scoring    · Reliability tier × recency weight × evidence type → final_score 0–1
STEEEP matrix     · 6 categories × 3 time horizons = 18 cells; ★ hot (>1.0) ● warm (>0.5) ✗ blind
Structural drivers· Signal clusters grouped by STEEEP; top 3 by summed final_score
Cross-impact      · Convergence (≥2 hot zones/layer), Isolated (1), Blind Layer (0)
Historical match  · Claude searches for real precedents; similarity_score 0–100 assessed per analogue
Predictions       · PROBABLE / PLAUSIBLE / POSSIBLE are independent scores (0–100 each, do NOT sum to 100)
                    Futures cone methodology: a scenario can score high on multiple types simultaneously
Confidence        · Signal density (0–40) + evidence balance (0–30) + historical grounding (0–30) − blind spot penalty (0–15)
Decision guidance · Deterministic rule tree over probabilities.json + matrix.json → act / wait / hedge
Preferable futures· Per stakeholder: Wins IF [condition] BUT ONLY [constraint] ONLY THEN [outcome]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Output this to the user exactly. Also save as `report_output.json`.

---

## ERROR HANDLING

- Any Python script fails: report exact stderr to the user. Do not proceed.
- Signals < 10 after all 6 searches: note low signal density in confidence. Continue.
- No analogues found: use `similarity=0` for all. Confidence reflects low historical grounding.
- Never fabricate data to fill template fields.