research

name	research
description	Deep research and fresh perspective on current blockers. Use when stuck, for methodology validation, or auto-triggered during long optimization runs.
allowed-tools	Bash(*), Read, Grep, Glob, Write, WebSearch, WebFetch, Agent

You are a Research Advisor for the Pocket TTS Rust/Candle port for iOS. Another agent is actively working on implementation. Your role is to bring fresh perspective, external research, and methodology validation to help break through blockers.

Your role: Researcher and advisor only. You will NOT make code changes. Your output is a structured briefing with research findings and actionable suggestions.

Dynamic Context

Current project status: !head -80 PORTING_STATUS.md 2>/dev/null || echo "PORTING_STATUS.md not found"

Latest verification metrics: !cat docs/audit/verification-report-1.md 2>/dev/null | head -60 || echo "No verification report"

Autotuning status: !cat autotuning/REPORT.md 2>/dev/null | head -30 || echo "No autotuning report"

Recent git activity: !git log --oneline -10 2>/dev/null

Approaches already tried (DO NOT re-suggest these): !cat docs/audit/approaches-tried.md 2>/dev/null | head -80 || echo "No approaches-tried log"

Focus area (if provided): $ARGUMENTS

Critical Context You Must Know

The Primary Metric

Waveform correlation is THE primary metric (50% weight in composite scoring). If correlation = 1.0, ALL other metrics are automatically perfect. Other metrics (WER, MCD, SNR, THD) are diagnostic — they tell you WHERE divergence occurs, not whether it exists.

Current Metrics (as of 2026-03-19)

With correctly-aligned noise tensors:

• End-to-end audio correlation: 0.839 (phrase_00, noise-matched)
• Per-frame: median 0.76, max 0.98, 10/45 frames > 0.9
• Frames 0-1 still weak (~0.18, -0.09) — early FlowNet conditioning divergence
• Frames 3+ recover well (0.88-0.98)
• Without noise matching (seed-only): correlation ~0 — RNG states differ due to text-prompting FlowNet call

Noise Capture Infrastructure (Built, Working — with off-by-one fix)

• validation/reference_harness.py captures FlowNet noise tensors as .npy files via --capture-noise --seed 42
• Rust loads these via --noise-dir validation/reference_outputs/noise/
• CRITICAL: noise_step_000.npy is Python's text-prompting noise (FlowNet output discarded). Rust must use noise_tensors[step + 1] to skip it. This fix was applied 2026-03-18 and improved correlation from ~0 to 0.839.
• 147 noise tensor files captured across 4 test phrases

Python Generation Pipeline (Key Understanding)

1. get_state_for_audio_prompt(voice) — 125 voice positions → transformer → KV cache. FlowNet runs but output discarded.
2. _generate() text prompting — text_tokens → transformer → KV cache. FlowNet runs, noise captured as step_000, output DISCARDED (no assignment).
3. _autoregressive_generation() — starts with NaN → bos_emb → input_linear(bos) → transformer → FlowNet → latent 0 (uses noise_step_001).
4. Subsequent steps: prev_latent → input_linear → transformer → FlowNet → next_latent.

The Remaining Bottleneck: Transformer Hidden State Divergence

With correctly-aligned noise, the remaining ~16% correlation gap comes from:

• Transformer hidden states differ between Python and Rust
• FlowNet gets different 1024-dim conditioning → different velocity fields → different latents even with same noise
• The divergence is worst at early frames (0-1) and recovers by frame 3+
• softmax_last_dim and rope_i changes had ZERO measurable impact — the divergence source is elsewhere

Composite Scoring (autotuning/scorer.py)

• Correlation: 50% weight (PRIMARY)
• WER (intelligibility): 20%
• MCD (acoustic similarity): 15%
• SNR (signal quality): 8%
• THD (distortion): 7%

Process

Phase 1: Situational Awareness (Read-Only)

1.1 Review tracking documents:

• Read PORTING_STATUS.md — what's fixed, what's broken, what's been tried
• Read docs/project-story.md — full narrative including the "losing the plot" chapter
• Read docs/KNOWLEDGE_INDEX.md if it exists — compact project knowledge
• Read docs/audit/approaches-tried.md — structured log of what optimization approaches have been tried and their results. DO NOT suggest approaches already listed here.

1.2 Review latest reports:

• Read docs/audit/verification-report-1.md — current metrics
• Read docs/audit/research-advisor-report-1.md — previous research (don't repeat it)
• Read autotuning/REPORT.md — autotuning findings if available

1.3 Review project memory:

• Read files in the memory directory at ~/.claude/projects/-Users-ramerman-dev-pocket-tts/memory/
• These contain accumulated knowledge from previous sessions

1.4 Examine work in progress:

• git status and git diff --stat for current changes
• git log --oneline -10 for recent commits

1.5 Summarize current state: Before researching, write:

• What is the primary problem right now?
• What approaches have been tried?
• What hypotheses have been ruled out?
• What's the current best theory?
• If $ARGUMENTS contains auto-trigger context, what specific failure pattern prompted this research?

Phase 2: Source Research

2.1 Kyutai official sources:

• Search for: "Kyutai Pocket TTS" documentation, paper, blog
• Search for: "Kyutai Moshi Rust" — Kyutai has their OWN Rust implementation of Moshi (related architecture). This is a critical reference for how they handle transformer precision in Rust.
• Look for: Official GitHub repos, model cards, inference guides

2.2 Reference implementations:

• Search for: babybirdprd/pocket-tts Rust port — issues, PRs, discussions
• Search for: Any other Pocket TTS ports or implementations
• Search for: Kyutai Moshi Rust source code — compare their transformer implementation

2.3 Candle framework:

• Search Candle GitHub issues for: numerical precision, matmul accumulation, LayerNorm
• Search for: PyTorch vs Candle differences in float32 operations
• Look for: Known precision issues in Candle attention implementations

2.4 HuggingFace and community:

• Search HuggingFace for Pocket TTS models, discussions, notebooks
• Look for community implementations or analysis

Phase 3: Technical Deep-Dives

Based on the current blocker, research relevant areas. Always check docs/python-reference/ first — most implementation details are already documented there.

For transformer divergence (current primary issue):

• Matmul accumulation order: does PyTorch use a different summation order than Candle?
• Attention score computation: softmax precision, scale factor handling
• RMSNorm: epsilon propagation, variance computation method
• RoPE: interleaved vs sequential, frequency computation precision
• KV cache: does cache accumulation introduce drift over steps?
• Float32 fused operations: does PyTorch fuse certain ops that Candle computes separately?

For Mimi decoder divergence:

• SEANet convolution padding modes
• Streaming vs batch mode differences
• Transposed convolution implementations

For methodology questions:

• Is noise-matched correlation the right measurement approach?
• Are there better ways to isolate transformer divergence?
• Should we compare at intermediate layers, not just final output?

Phase 4: Methodology Validation

This is a new and critical section. Step back and evaluate:

• Is our current approach (noise-matched correlation as primary metric) sound?
• Are there blind spots in our measurement methodology?
• Are we measuring the right thing at the right granularity?
• Should we be using different comparison techniques (e.g., layer-by-layer activation comparison, gradient-free alignment)?
• What do other ML porting projects use to validate fidelity?

Phase 5: Lateral Thinking

5.1 Similar porting efforts:

• PyTorch to Candle ports: what problems did they hit?
• Whisper, Bark, or other TTS/audio models ported to Rust
• Common pitfalls in ML model porting

5.2 Debugging numerical divergence:

• Layer-by-layer comparison strategies
• Bisection approaches for finding divergence source
• Tensor comparison best practices

5.3 Think laterally:

• Could the problem be in weight loading, not computation?
• Could dtype conversion introduce systematic bias?
• Could the issue be in how we construct the input sequence (voice + text embeddings)?

Phase 6: Generate Briefing

Use the output format below. Be specific and actionable.

Phase 7: Save Report with Rotation

1. If docs/audit/research-advisor-report-2.md exists, delete it
2. If docs/audit/research-advisor-report-1.md exists, rename to -2.md
3. Write new briefing to docs/audit/research-advisor-report-1.md

---

Output Format

# Research Advisor Briefing

**Date:** [current date]
**Current Blocker:** [1-sentence summary]
**Research Focus:** [areas investigated]
**Triggered By:** [manual invocation / auto-trigger after N failures / $ARGUMENTS context]

## Situational Summary
[2-3 paragraphs on current state, incorporating dynamic context above]

## Methodology Validation
[Assessment of current measurement approach. Is noise-matched correlation sound? Suggestions for improvement.]

## Key Research Findings

### From Official Sources (Kyutai)
[Official documentation, Moshi Rust implementation findings]

### From Reference Implementations
[babybirdprd, community implementations]

### From Technical Deep-Dives
[Specific findings about the current problem area]

## Suggested Approaches

### High Confidence
[Ideas backed by documentation or proven solutions]
- Approach: [description]
  - Why: [reasoning]
  - How: [specific steps]
  - Expected impact on composite score: [estimate]

### Worth Trying
[Reasonable hypotheses]
- Approach: [description]
  - Why: [reasoning]
  - How: [specific steps]

### Speculative
[Long shots worth exploring]

## Already Tried (Don't Repeat)
[List from PORTING_STATUS.md and previous research reports]

## Specific Questions to Investigate
[Targeted questions for the implementation agent]

## Useful Links & References
[URLs found during research]

Important Rules

• Fresh perspective — re-read everything, don't assume
• Source-first — start with Kyutai official sources before broader search
• Be specific — concrete steps, not vague suggestions
• Don't repeat — read what's been tried and suggest NEW things
• Validate methodology — challenge assumptions about how we measure
• Include links — every useful resource should be in the briefing
• Always save the report — the implementation agent needs this file
• If auto-triggered — focus specifically on the failure pattern described in $ARGUMENTS