HSG_RAG

Executable, decision-gated campaign for the project's hardest live problem (as of 2026-07-07) — improving answer quality and the conversion of chats into advisor appointments. Load this when asked to "improve conversion", "get more bookings", "improve answer quality", "measure the funnel", "check the overhaul defects", "tune the booking widget", or to plan any prompt/UX change whose goal is more advisor appointments. Do NOT load for bug triage (hsg-rag-debugging-playbook) or for running tests as such (hsg-rag-validation-and-qa).

Domain knowledge pack for the HSG Executive MBA advisory chatbot. Load this when a task touches programme facts (EMBA HSG / IEMBA HSG / emba X), tuition or deadline logic, advisors and Calendly booking, the admissions/conversion funnel and its structured-response flags (appointment_requested, show_booking_widget, relevant_programs), language/naming rules (bare "EMBA", British English, "HSG" usage), positioning and tone rules, or GDPR-relevant data flows (consent, user profiles, log masking, US processing). Also load it before editing prompts, response schemas, or any test that asserts programme facts.

Load-bearing design decisions, system invariants, and known weak points of the HSG_RAG chatbot. Load BEFORE changing anything in src/rag/ or src/apps/chat/, before adding caching/sub-agents/routers/new LLM roles, when asking "why is there no X here", when tracing the request path end to end, or when a change might violate an invariant (fact contamination, consent gate, streaming, log redaction). Explains WHY the architecture is shaped this way so you don't reintroduce a removed failure.

How changes are classified, gated, reviewed, and rolled back in the HSG_RAG repo. Load BEFORE editing any file, opening a PR, merging, deploying, adding a dependency, or touching programme_facts.json, prompts, workflows, or the Caddyfile. Also covers the non-negotiable rules (with the incidents behind them), the sanctioned alert-chain test, and the production rollback protocol.

Symptom-to-triage playbook for diagnosing WHY something in the HSG RAG chatbot is broken or slow. Load when you need to find the cause of — slow answers, missing token streaming, error messages instead of answers ("Es tut mir leid, ich kann im Moment keine hilfreiche Antwort geben"), wrong programme prices, the booking widget never shows/appears, bot unreachable, blank iframe, empty PDF extraction in the facts pipeline, flaky LLM-judge tests, container start problems, or confusing log lines like "empty response" / "falling back to blocking invoke". Contains discriminating experiments with exact commands and the historical trap behind each failure mode. (To MEASURE current state with scripts — health, latency numbers, counts — use hsg-rag-diagnostics-and-tooling instead.)

Run, deploy, and operate the HSG_RAG chatbot. Load this skill when you need to: start the app locally (main.py flags), understand the production topology (Hetzner host, Docker container, Caddy), deploy a change (merge = deploy), trigger or observe a deployment, roll back a bad deploy, change the Caddyfile (TLS/CSP), check the scheduled GitHub Actions (nightly facts update, weekly scrape), or read/interpret the production logs. Triggers: "run the app", "deploy", "rollback", "production", "server", "container", "Caddy", "logs", "health check", "cron", "scheduled workflow", "start the bot".

How to communicate with the four external parties this project depends on — HSG-IT (DNS/zone changes), the EMBA web team (WordPress iframe embedding), the Datenschutzbeauftragte:r (GDPR sign-off), and advisors/EMBA marketing (contact/Calendly changes). Load when drafting a request to any of these parties, when the user says "schreib eine E-Mail an IT/Webteam/DSB", when an iframe embed fails on the target page, when DNS/CAA records are needed, when advisor contact data must change, or when deciding WHO must be contacted for a given failure. Contains proven German templates.

The chronicle of every major HSG_RAG failure, dead end, rejected fix, and revert — response cache saga, June 2026 latency/hallucination overhaul, regex fact router, sub-agent removal, Weaviate 404 outage, HF Space era, streaming bugs, judge flakiness, dead branches. Load this BEFORE proposing a caching layer, sub-agents, regex fact extraction, model swaps, or any "why don't we just…" idea; before investigating a bug that smells historical; before resurrecting code from an old branch; or when asked "has this been tried before?". Prevents re-fighting settled battles.

What counts as evidence in HSG_RAG and how to produce it. Load when you need to run or interpret the test suites (offline pytest, RUN_LLM_EVAL 34-case fact eval, RUN_UAT_LLM_JUDGE), decide which gates a change must pass before merge, add a new test / eval case / UAT conversation, judge whether a failing case is a flake or a regression, or understand the uat-results golden inventory and the CI gates (pr-llm-eval.yml, main-smoke.yml). Not for debugging failures (use hsg-rag-debugging-playbook) or changing the gates themselves (use hsg-rag-change-control).

Recreate the HSG_RAG development environment from scratch and avoid its known traps. Load when setting up a fresh clone, creating a venv, installing dependencies, configuring .env, building the Docker image, hitting "No module named pytest", a python-dotenv AssertionError, torch/CUDA download surprises, or any "works in prod but not locally" environment mismatch. NOT for running/deploying the app (hsg-rag-run-and-operate) or test strategy (hsg-rag-validation-and-qa).

Catalog of every configuration axis in HSG_RAG — model/provider settings, chain knobs (TOP_K, history cap, word budgets), scraping parameters, Weaviate timeouts, notification toggles, environment variables, and GitHub Actions secrets. Load this when you need to know what a config value does, what its real default is, whether it is production-active or legacy, how config.py / env var / code-default precedence works, or how to add a new config axis. Also covers the env-var precedence trap that silently ignores NOTIFY_* overrides.

Measure instead of eyeball — diagnostic scripts and interpretation guides that quantify the HSG RAG chatbot's CURRENT state. Load when you need to measure production health, measure latency or time-to-first-token numbers, verify Weaviate object counts after an import, run public smoke tests over the Gradio API, scan the Docker image for CVEs (Trivy), or watch GitHub Actions runs (deploy, programme facts). Triggers: "is prod healthy", "measure latency", "get timing numbers", "verify streaming is alive", "smoke test", "Weaviate counts", "how many objects", "Trivy scan", "watch the deploy run", "timing logs". If something is broken and you need the CAUSE, load hsg-rag-debugging-playbook instead.

How to maintain HSG_RAG's documents of record and match its house style. Load when writing or updating README.md, DEPLOYMENT_CHECKLIST.md, AGENTS.md, anything under docs/, a post-mortem/audit, a commit message, a PR body, or a new skill in .claude/skills/ — or when unsure which document a new fact belongs in, which language to write in, or how to check off a checklist item correctly.

First-principles analysis recipes for HSG_RAG — prove a mechanism instead of patching a symptom. Load when you are about to claim a root cause, ship a performance change, verify a multi-system chain (alerts, deploys), blame the LLM for a wrong answer, migrate models/providers, or audit dependencies. Each recipe includes a worked example from this repo's real history with commits and numbers. NOT a symptom→fix lookup table (that is hsg-rag-debugging-playbook) and not the chronicle of past incidents (that is hsg-rag-failure-archaeology).

Open research problems where HSG_RAG could advance the state of the art. Load when asked "what should we research next", "how could this bot be best-in-class", "can we publish something", "EU/sovereign LLM migration", "conversion measurement research", "bilingual retrieval parity", or "personalization under GDPR" — or when planning work that is exploratory rather than a bugfix or feature request. Provides, per problem: why current SOTA falls short, this repo's specific asset, the first three concrete in-repo steps, and a falsifiable "you have a result when…" milestone.

How a hunch becomes an accepted change in HSG_RAG — the evidence bar, predict-numbers-before-running, the idea lifecycle from proposal to merge or documented retirement, and where good ideas historically came from. Load this BEFORE starting any investigation, experiment, prompt change, latency/conversion improvement, or "I think the problem is X" hypothesis work. Also load it when deciding whether a result is strong enough to propose, or whether an idea should be retired.