docs: clarify interactive mode routing behaviour and log UX friction risk

[hannasdev]

Summary

• Clarify in README that switchboard --interactive fixes model/effort at launch and does not automatically re-route between turns inside the running Claude session.
• Add a dedicated Interactive Mode Clarification subsection in README explaining the per-turn vs interactive tradeoff and when each pattern is appropriate.
• Add decision log entry DEC-2026-05-13-per-turn-routing-ux-friction recording the UX friction risk, four options considered, and the committed direction.
• Update PRODUCT-PRD.md deferred item for in-session model switching to reflect the committed Option B direction and planned client surface survey.

Motivation

Manual testing of interactive mode surfaced a gap: the continuity assumption in MVP-PRD.md was verified against technical criteria (session IDs persist, chat history carries over) but not against the actual interaction pattern the user must follow to obtain per-turn routing. Per-turn routing requires exiting and re-entering Claude each turn, trading model-selection cognitive cost for session-cycling cognitive cost. This risks limiting adoption among the target user who is already comfortable staying inside Claude Code.

Implementation

No code changes. All changes are documentation only:

• README.md: two targeted edits to the high-level flow and command table, plus a new clarification subsection.
• docs/decision-log.md: new committed decision entry with full options, tradeoffs, and follow-up plan.
• docs/product/PRODUCT-PRD.md: one-line update to the deferred item description for in-session model switching.

The decision commits to two follow-up workstreams:

1. Harden hook-based advisory injection (Option B) so the routing recommendation surfaces inside the running Claude session via UserPromptSubmit.
2. Survey alternative client surfaces (Cursor, GitHub Copilot Chat, Gemini CLI, gateway-backed paths) for better per-turn routing integration points.

Testing

• npm test: 98/98 passing (docs-only change, no test impact).
• npm run lint: clean (enforced by pre-commit hook).
• Manual review of README rendering confirmed section order and content are correct.

Risks and tradeoffs

Low risk. Documentation-only change. The clarification reduces the chance of users being misled about interactive mode behaviour; it does not remove any functionality.

Follow-up

• Implement and live-verify improved advisory injection in the hook bridge.
• Complete client surface survey.
• Revisit Option C (true in-session switching) and Option D (reframe product promise) based on survey findings before broad adoption promotion.

[Copilot]

Pull request overview

This PR updates product documentation to clarify that switchboard --interactive fixes model/effort at launch and does not perform per-turn re-routing within an active Claude interactive session, and records the resulting UX tradeoff as a committed product decision.

Changes:

• Clarifies README flow/command behavior and adds an “Interactive Mode Clarification” subsection describing interactive vs per-turn routing tradeoffs.
• Adds a committed decision-log entry documenting the per-turn routing UX friction risk and the chosen near-term direction (hook-based advisory injection).
• Updates the deferred “in-session automatic model switching” item in the product PRD to reflect the committed direction and planned client-surface survey.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
README.md	Clarifies interactive mode behavior and documents when to use interactive vs per-turn routing.
docs/product/PRODUCT-PRD.md	Updates deferred roadmap item to reflect the committed advisory-injection direction and survey plan.
docs/decision-log.md	Adds a new committed decision entry capturing the UX friction risk and chosen option.

Comments suppressed due to low confidence (1)

docs/decision-log.md:329

• Same as above: format the hook/event name UserPromptSubmit as inline code (backticks) for consistency with other docs (and with PreToolUse).

Consequences:
- Near-term implementation impact: hook bridge advisory injection path needs to be hardened so that each UserPromptSubmit event surfaces a clear, low-noise routing recommendation the user can act on or ignore. This is distinct from current advisory context injection which is primarily for correlated logging.
- Test and replay impact: new advisory injection behavior should be covered by hook bridge tests to ensure recommendation accuracy and noise level are acceptable.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.