# Integration Notes — Phase D Handoff

**Document Type:** Phase D Integration Backlog
**Created:** 2026-04-10
**Owner:** Phase D Integrator

This file records decisions made during Phase C iteration that require action at Phase D integration time. Items are written by the Commander (not individual team Iterators) and should be actioned before declaring the system production-ready.

---

## Item INT-001: Improve `/ai-fallback` skill to handle hang (not just quota)

**Source:** Team 1 Cycle 2 diff — rejected as a spec change, promoted to Phase D integration item
**Decision date:** 2026-04-10
**Decision maker:** Commander (iteration cycle review)

### Background

Team 1 (Mini-Research Agent) observed across both Cycle 1 and Cycle 2 that Gemini 2.5 Flash can hang indefinitely without emitting output or an error. The current `/ai-fallback` skill only advances the fallback chain on explicit quota errors. A hang that produces no output is not recognized as an advance condition, so the chain stalls silently.

Team 1 proposed wrapping all `/ai-fallback` calls with `timeout 90` and an `|| websearch_fallback.sh` OR-fallback. This is valid behavior, but the fix belongs in the `/ai-fallback` skill itself — not in the mini-research-agent spec — because:

1. Any agent using `/ai-fallback` is exposed to this gap, not just Mini-Research.
2. Baking `timeout 90` into each agent spec creates redundancy and maintenance drift.
3. The right abstraction is: `/ai-fallback` should internally handle hang-as-advance, so callers do not need to know about this edge case.

### Required Phase D action

**Option A (recommended — deep fix):** Modify `~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh` to add a per-model internal timeout (e.g., 90 seconds per model attempt). If a model times out without producing output, treat it as an advance condition and move to the next model in the chain. This is transparent to all callers.

**Option B (quick fix — acceptable if Option A is deferred):** Create a new wrapper script `~/.claude/skills/ai-fallback/scripts/websearch_fallback.sh` that provides a deterministic secondary path when the primary chain produces no output within the timeout window. Callers would need to adopt the pattern: `timeout 90 bash call_with_fallback.sh "[prompt]" || bash websearch_fallback.sh "[prompt]"`. This is the pattern Team 1 proposed but it requires per-caller adoption.

**Recommended:** Option A, because it centralizes the fix and does not require updating any agent specs.

### Validation

After implementing either option, run Mini-Research Agent Cycle 3 on Input-B (the topic that reproduced the hang in Cycle 2) and verify the chain advances without manual intervention when Gemini 2.5 Flash hangs.

### Files to modify

- `~/.claude/skills/ai-fallback/scripts/call_with_fallback.sh` (Option A)
- OR `~/.claude/skills/ai-fallback/scripts/websearch_fallback.sh` (Option B — new file)

### References

- Team 1 Cycle 2 patch: `docs/iteration-team/team-1-workspace/diffs/cycle-2.patch`
- Team 1 Cycle 2 summary: `docs/iteration-team/team-1-workspace/diffs/cycle-2-summary.md`

---

## Item INT-002: Cycle 3 harness instruction — Mini-Writer Agent uses Input C with partial upstream

**Source:** Team 2 Cycle 2 diff — no spec change; harness instruction only
**Decision date:** 2026-04-10
**Decision maker:** Commander

### Background

Mini-Writer Agent has passed 12/12 BDD scenarios across Cycle 1 and Cycle 2. The `/ai-fallback` path (W-09) has never actually fired because upstream research files have been pre-verified and complete. This means W-09 is passing vacuously (zero fallback events, not proven unnecessary).

### Required Phase D / Cycle 3 action

Cycle 3 dispatch harness for Team 2 must:

1. Rotate to **Input-C** (Slide 12 — ADA closing force).
2. Provide a **partial** upstream research file that contains the 5 lbf interior / 8.5 lbf exterior numbers but **omits the ADA section citation**.
3. The writer must either:
   - Halt and report missing citation (acceptable — per spec anti-pattern rule), OR
   - Invoke `/ai-fallback` to verify the ADA section number (also acceptable — this is the desired W-09 evidence path).
4. Either outcome converts W-09 from "passing by absence" to "passing by observed behavior."

**No changes to `mini-writer-agent.md` are required.** This is a harness configuration instruction only.

---

*End of integration notes. Add new items below this line as Phase C continues.*