mathews-tom/immune

Immune System v3 — Hybrid Cheatsheet + Immune

You operate a hybrid adaptive system with two complementary memories:

• Cheatsheet (positive patterns): domain-specific strategies injected BEFORE generation to improve output quality
• Immune (negative patterns): antibodies that detect known errors and discover new threats AFTER generation

Both memories use Hot/Cold tiering to keep context lean.

Input Parsing

The user invokes with content to scan. Parse these parameters:

• input: The text/code/content to scan (required — either inline or from context)
• domain: One of: fitness, code, writing, research, strategy, webdesign, _global (default: auto-detect)
• domains: Array of domains (overrides single domain). Example: domains=fitness,code
• constraints: Any specific requirements the output should satisfy (optional)
• mode: full (cheatsheet + scan, default) | scan-only (skip cheatsheet) | cheatsheet-only (return cheatsheet, no scan)

<examples> <example> /immune Check this function for common pitfalls → domains=["code"] (auto-detected), mode=full </example> <example> /immune domain=fitness Vérifie ce programme de musculation → domains=["fitness"] (explicit) </example> <example> /immune domains=fitness,code Check this workout generator API → domains=["fitness", "code"] (multi-domain) </example> <example> /immune → scans the most recent output in the conversation </example> </examples>

If no inline text is provided, scan the last substantive output in the conversation.

Domain auto-detection: Read config.yaml (co-located with this skill) and match content against domain_keywords. If no strong match, use ["_global"]. If single domain string provided, wrap in array: domains = [domain].

Task-Conditioned Retrieval (v3.1.0+)

Antibodies and cheatsheet strategies may carry an optional triggers field for per-task filtering. This implements the read phase of the Memento-Skills reflective loop (arXiv 2603.18743) — entries are ranked by lexical overlap between the current task and their historical contexts.

Schema (additive, optional):

{
  "id": "AB-042",
  "domains": ["code"],
  "pattern": "SQL injection via string concatenation",
  "severity": "critical",
  "correction": "Use parameterized queries",
  "triggers": {
    "task_signatures": ["code query review sql", "audit code sql"],
    "domains": ["code"]
  }
}

Back-compat: entries without triggers behave as always-on (the v3.0.0 behavior). The task_conditioned_retrieval: true flag in config.yaml enables the filter. When disabled, all entries load regardless of task.

Ranking helper: scripts/retrieve.py implements the scoring logic. Callers (including the scanner agent, the skill-librarian in P2, and the skill-router in P3) invoke retrieve(prompt, entries, active_domains, historical_success) to obtain the ranked subset before tier classification. Scoring uses Jaccard similarity over normalized task signatures from scripts/task_signature.py, multiplied by an optional per-entry success rate derived from evals/history.jsonl.

During load (Phase 0 cheatsheet, Phase 1 antibodies), after the domain filter and before Hot/Cold tier classification, apply the retrieve step:

1. Compute task_signature(prompt) for the current task.
2. Pass entries through retrieve(...) with the active domains set.
3. Feed only the returned subset into the tier classification below.

Entries filtered out at retrieval never reach Hot/Cold — this is what keeps the scan context lean and task-focused.

Execution

Step 0 — Cheatsheet Injection (positive patterns)

Skip this step if mode == "scan-only".

0a. Load cheatsheet: Read cheatsheet_memory.json (co-located with this skill).

0b. Filter by domains: Keep strategies where ANY of the strategy's domains overlaps with the detected domains, OR strategy has "_global" in its domains.

0c. Classify into tiers (same logic as antibodies): A strategy is HOT if ANY of:

• effectiveness >= 0.7
• seen_count >= 3
• last_seen less than 30 days ago

Everything else is COLD.

0d. Cap HOT strategies: Sort by effectiveness descending, then seen_count descending. Keep max 15 (from config.yaml → cheatsheet.max_hot).

0e. Build cheatsheet block: Format HOT strategies as XML:

<cheatsheet domain="{domains}">
  <strategy id="{id}" effectiveness="{effectiveness}">
    {pattern}
    Example: {example}
  </strategy>
  ...
</cheatsheet>

If there are COLD strategies, add a one-liner:

<cheatsheet_cold>Also consider: {comma-separated COLD pattern keywords}</cheatsheet_cold>

If mode == "cheatsheet-only", output the cheatsheet block and stop here.

Log:

[IMMUNE] Cheatsheet: {n_hot} HOT + {n_cold} COLD strategies (domains: {domains})

0f. Present cheatsheet to user: If running standalone (/immune), show the cheatsheet as context the user should apply to their next generation. If called by another system, return the XML block for injection into prompts.

Step 1 — Load & Classify Antibodies (Hot/Cold)

Read immune_memory.json and config.yaml (co-located with this skill).

1a. Filter by domains: Keep antibodies where ANY of the antibody's domains overlaps with detected domains, OR antibody has "_global" in its domains.

Backwards compatibility: If an antibody has "domain" (string) instead of "domains" (array), treat it as domains = [domain].

1b. Classify into tiers: For each filtered antibody, classify as HOT if any of these is true:

• severity == "critical"
• seen_count >= 3
• last_seen is less than 30 days ago (relative to today's date)

Everything else is COLD.

1c. Cap HOT antibodies: Sort HOT by: severity (critical > warning > info), then seen_count descending. Keep max 15 (from config.yaml → tiers.hot.max_per_scan). If more than 15 qualify as HOT, overflow goes to COLD.

1d. Build COLD summary: For each COLD antibody, extract a short keyword from its pattern field. Join as comma-separated list. Example: "SQL transactions, épicondylite, debug flags, tautologies"

Log:

[IMMUNE] Tier split: {n_hot} HOT + {n_cold} COLD / {total} total (domains: {domains})

Step 2 — Scan

Spawn the immune-scan agent (Haiku) with the following XML-structured prompt:

<scan_request>
  <domains>{detected_domains as JSON array}</domains>
  <task>{task description or "Scan the following content for errors and threats"}</task>
  <constraints>{constraints or "none"}</constraints>

  <content>
{the input text/code/content to scan}
  </content>

  <hot_antibodies>
{JSON array of HOT antibodies — full objects with id, domains, pattern, severity, correction}
  </hot_antibodies>

  <cold_summary>
Dormant patterns (not detailed, for awareness only): {comma-separated COLD keywords}
  </cold_summary>

  <cheatsheet_applied>
{list of strategy IDs and patterns that were injected in Step 0, or "none" if scan-only mode}
  </cheatsheet_applied>
</scan_request>

Log: [IMMUNE] Scanning... ({n_hot} active antibodies) Wait for result.

If corrections applied: Log: [IMMUNE] Match {antibody_id}: {original} → {corrected} If new threats detected: Log: [IMMUNE] New threat: {pattern} If new strategies detected: Log: [IMMUNE] New strategy: {pattern}

Step 3 — Update Immune Memory (with COLD deduplication)

Read current immune_memory.json.

3a. Matched HOT antibodies: For each antibody matched by the scanner, increment seen_count and update last_seen to today.

3b. New threats — deduplicate against COLD: For each new threat in new_threats_detected:

1. Compare its pattern against ALL COLD antibodies (fuzzy match — same domains + similar keywords).
2. If it matches a COLD antibody → REACTIVATE:
   • Increment the COLD antibody's seen_count
   • Update its last_seen to today
   • Log: [IMMUNE] Reactivated COLD antibody {id}: {pattern}
   • Do NOT create a new antibody (prevents duplicates)
3. If no COLD match AND auto_add_threats is true → CREATE new antibody:
   • id: "AB-{next_number}"
   • domains: from the threat's recommended_antibody.domains (array)
   • pattern, severity, correction: from the threat's recommended_antibody
   • seen_count: 1
   • first_seen: today's date
   • last_seen: today's date
   • Log: [IMMUNE] + New antibody {id}: {pattern}

3c. Update stats:

• Increment stats.outputs_checked
• Increment stats.issues_caught by number of corrections + new threats
• Update stats.antibodies_total to current antibody count

Write back to immune_memory.json.

Log: [IMMUNE] Memory: {total} antibodies ({n_hot} hot, {n_cold} cold) | +{new} added | Reactivated: {reactivated}

Step 3b — Update Cheatsheet Memory (positive patterns)

Skip if mode == "scan-only" or no new_strategies_detected in scan result.

Read current cheatsheet_memory.json.

3b-i. Deduplicate: For each new strategy in new_strategies_detected:

1. Compare against ALL existing strategies (fuzzy match — overlapping domains + similar pattern).
2. If it matches an existing strategy → REINFORCE:
   • Increment seen_count
   • Update last_seen to today
   • Adjust effectiveness: new_eff = old_eff * 0.8 + reported_eff * 0.2 (exponential moving average)
   • Log: [IMMUNE] Reinforced strategy {id}: {pattern} (eff: {old}→{new})
3. If no match AND auto_add_strategies is true → CREATE new strategy:
   • id: "{prefix}-{next_number}" (prefix from config.yaml → cheatsheet.id_prefix.{domain})
   • domains: from the strategy (array)
   • pattern, example: from the strategy
   • effectiveness: from the strategy (or config.yaml → cheatsheet.default_effectiveness)
   • seen_count: 1
   • first_seen: today's date
   • last_seen: today's date
   • Log: [IMMUNE] + New strategy {id}: {pattern}

3b-ii. Prune low-effectiveness: If any strategy has effectiveness < config.cheatsheet.min_effectiveness AND seen_count >= 5:

• Remove it
• Log: [IMMUNE] - Pruned strategy {id}: {pattern} (eff: {eff})

3b-iii. Update stats:

• Increment stats.outputs_assisted
• Increment stats.strategies_applied by number of cheatsheet strategies that were used
• Update stats.strategies_total to current count

Write back to cheatsheet_memory.json.

Log: [IMMUNE] Cheatsheet: {total} strategies | +{new} added | Reinforced: {reinforced}

Step 4 — Output

If clean:

───
IMMUNE v3 | domains={domains} | Status: CLEAN
   Cheatsheet: {n_strategies} strategies applied | Antibodies: {n_hot}/{max} HOT, {n_cold} COLD
   No issues detected
───

If corrections or threats found:

───
IMMUNE v3 | domains={domains} | Status: {CORRECTED|FLAGGED}

Corrections Applied:
  [AB-XXX] {pattern} → {correction}

New Threats Detected:
  [{severity}] {pattern} — {suggested_correction}

Reactivated:
  [AB-XXX] {pattern} (was COLD, now HOT)

New Strategies Learned:
  [CS-XXX] {pattern} (eff: {effectiveness})

───
Corrected Output:
{the corrected content, formatted for the domain}
───
Memory: {total_ab} antibodies + {total_cs} strategies | +{new_ab} AB | +{new_cs} CS
───

Then present the corrected output in a human-readable format appropriate to the domain.

Error Handling

• If immune_memory.json does not exist: create it with {"version": 3, "antibodies": [], "stats": {"outputs_checked": 0, "issues_caught": 0, "antibodies_total": 0}}
• If cheatsheet_memory.json does not exist: create it with {"version": 3, "strategies": [], "stats": {"outputs_assisted": 0, "strategies_applied": 0, "strategies_total": 0}}
• If immune_memory.json has "version": 2: auto-migrate by converting each antibody's "domain" to "domains": ["domain_value"] and set version to 3. Write back immediately.
• If the agent returns invalid JSON: retry once. If still invalid, report the raw output with a warning.
• If no input is provided and no recent output exists: ask the user what to scan.
• If all antibodies are COLD (none qualify as HOT): still send the scan with empty hot_antibodies array and full cold_summary. Haiku can still detect new threats via Phase 2.