# Suite8 True Specialist Discovery Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build Suite8 as a controlled Suite7 extension in which residual experts receive distinct learned latent views and are regularized against ownership collapse.

**Architecture:** Reuse the Suite5 canonical cache and Suite7 shared-private data/training/evaluation flow. Add a KxD latent ownership matrix after all Suite7-equivalent modules, derive identity-centered expert-specific feature scales, feed a separate view to each residual expert, and add ownership-entropy plus load-balance losses.

**Tech Stack:** Python 3, PyTorch, NumPy, pandas, scikit-learn-compatible cached artifacts, pytest.

**Spec:** `docs/2026-08-26-suite8-true-specialist-discovery-design.md`

## Global Constraints
- Target remains `target_grade10 < 5`.
- Committee/cache are read-only and unchanged.
- Suite7 faculty adapter remains 128->16->128 with normal down / zero up initialization.
- Shared/raw feature schema remains exactly the Suite5 schema.
- Holdout labels never enter training, epoch selection, threshold selection, or warning-rate selection.
- Suite8 must compare against existing Committee, Suite5 Shared, and Suite7 Adapter predictions without retraining those baselines.
- Default expert count remains 4.

---

### Task 1: Learned-view model and losses

**Files:**
- Create: `suite8_true_specialist_moe.py`
- Test: `tests/test_suite8_model.py`

**Interfaces:**
- Produces `TrueSpecialistSharedPrivateResidualMoE.forward(...)` with Suite7-compatible outputs plus `expert_views`, `view_ownership`, and `view_scales`.
- Produces `suite8_residual_moe_loss(...)` with Suite7 losses plus `view_entropy` and `view_balance`.

- [ ] Write tests that require: initial final probability equals Committee; uniform ownership gives unit scales; ownership columns sum to one; view loss is finite; one optimizer sequence changes ownership logits; Suite7-equivalent module initialization is preserved before view logits are constructed.
- [ ] Run those tests and confirm failure because the Suite8 model module is absent.
- [ ] Implement the model and view-specialization losses minimally.
- [ ] Run the model tests to green.

### Task 2: Specialization diagnostics

**Files:**
- Extend: `suite8_true_specialist_moe.py`
- Test: `tests/test_suite8_diagnostics.py`

**Interfaces:**
- Produces ownership entropy/load/cosine diagnostics, expert-view cosine diagnostics, residual correlation rows, and counterfactual utility diagnostics.

- [ ] Write tests for known synthetic ownership matrices and utility winners.
- [ ] Run them to confirm the new diagnostic functions are missing/failing.
- [ ] Implement diagnostics and re-run to green.

### Task 3: Chronological trainer and baseline comparison

**Files:**
- Create: `train_suite8_true_specialist.py`
- Create: `suite8_reporting.py`
- Test: `tests/test_suite8_smoke.py`

**Interfaces:**
- Consumes Suite5 cache, Suite5 result directory, and Suite7 result directory.
- Produces per-fold Suite8 models/scores plus four-way Committee/Shared/Adapter/Specialist metrics.

- [ ] Write a synthetic cache + Suite5/Suite7-reference smoke test that calls the Suite8 CLI for a tiny chronological multi-faculty run.
- [ ] Run and confirm failure because trainer/reporting modules are absent.
- [ ] Implement training by adapting the Suite7 flow while changing only model/loss/diagnostics.
- [ ] Save four-way fold metrics and development-frozen fixed/drift policies.
- [ ] Run the smoke test to green.

### Task 4: Research outputs and documentation

**Files:**
- Create: `README_suite8.txt`
- Create: `tests/test_suite8_reporting.py`

**Interfaces:**
- Produces `suite8_true_specialist_comparison.csv`, `suite8_collapse_summary.csv`, `suite8_expert_ownership.csv`, `suite8_counterfactual_utility.csv`, `suite8_specialist_diagnostics.csv`, and optional `suite8_official_comparison.csv`.

- [ ] Write reporting tests for Suite8-minus-Suite7 deltas and evidence labels.
- [ ] Run to RED.
- [ ] Implement comparison/reporting and README run instructions.
- [ ] Run reporting tests and full test suite to green.

### Task 5: Final verification and package

**Files:**
- Package: `/mnt/data/suite8_true_specialist_discovery.zip`

- [ ] Run full pytest suite.
- [ ] Compile all Python files with `python -m py_compile`.
- [ ] Run CLI `--help`.
- [ ] Run the end-to-end synthetic smoke test fresh.
- [ ] Verify ZIP integrity with `unzip -t`.
