FALLBACK-1: fallback pipeline plugin specification

[JarbasAl]

Companion issue: #48

Summary

Defines the fallback pipeline plugin — the final stage(s) in the utterance lifecycle that handle utterances no earlier stage claimed, by querying registered fallback skills in priority order and dispatching to the first willing one.

The defining property of a fallback skill is that it evaluates the utterance with its own logic rather than relying on registered intents. Regular skills declare coverage through INTENT-4; fallback skills receive the raw utterance at query time and decide for themselves — analogous to CONVERSE-1's per-skill poll.

What the spec covers

• §3 — Skill registration (ovos.fallback.register / .deregister) with priority hint; session-scoped per INTENT-4 §11
• §3.3 — Priority guidance: 0–49 high confidence (knowledge bases), 50–74 medium (web search), 75–100 low confidence (LLM catch-alls). Every deployment SHOULD include a catch-all at priority 100
• §4 — Session field session.fallback_handlers (ordered preference list, same composition model as transformers)
• §5 — Pool construction: preference → stage range → availability → session.blacklisted_skills
• §6 — Match contract: sequential unicast ping/pong (<skill_id>.fallback.ping / <skill_id>.fallback.pong); request carries utterances + lang so skill can parse the utterance itself
• §7 — Dispatch via <skill_id>:fallback (reserved intent name, PIPELINE-1 §7.3)
• §8 — Pipeline positioning; multi-stage interleaving (fallback_high/medium/low) preserved via per-instance priority ranges

Companion edits (same PR)

• ovos-pipeline-1.md §7.3 — reserve intent_name fallback
• ovos-session-1.md §3 — register fallback_handlers field

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 552a4fee-0313-43fd-ad86-13d6610d7461

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch spec/fallback

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[JarbasAl]

Merge-readiness: resolved.

Merges resolved across two commits (c158adf + db0bace):

1. dev merge (auto): Added AUDIO-IN-1 spec file and compliance fix (owner_id→skill_id in ovos-session-1.md + ovos-stop-1.md). No conflict — dev's clean fast-forward context.
2. Remote branch catch-up (db0bace): Remote spec/fallback had 4 commits (rewrite + rename fallback.request/response → fallback.ping/pong) not in local. Conflict in ovos-session-1.md: dev had removed the fallback_handlers row (it wasn't there yet), remote added it. Preserved the PR's normative content: fallback_handlers | array of string | OVOS-FALLBACK-1 §4 kept.

Added FALLBACK-1, COMMON-QUERY-1, BRIDGE-1 in-review rows to README spec table.

No other semantic flags. Cross-references in fallback.md use spec IDs only.

Note on #55: fallback.md filename reference in README will need updating if filename-rename PR merges first.