تشغيل أي مهارة في Manus بنقرة واحدة

hsg-rag-docs-and-writing

النجوم٣

التفرعات١

آخر تحديث٨ يوليو ٢٠٢٦ في ٠١:٢٧

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.

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

koizachek

koizachek/HSG_RAG

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

مطوّرو البرمجياتمهن الحاسوب والرياضيات·SOC 15-1252

SKILL.md

readonly

المزيد من هذا المستودع

نفس المستودع

hsg-rag-conversion-campaign

koizachek/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).

2026-07-173

emba-domain-reference

koizachek/HSG_RAG

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.

2026-07-173

hsg-rag-architecture-contract

koizachek/HSG_RAG

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.

2026-07-173

hsg-rag-change-control

koizachek/HSG_RAG

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.

2026-07-173

hsg-rag-debugging-playbook

koizachek/HSG_RAG

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.)

2026-07-173

hsg-rag-run-and-operate

koizachek/HSG_RAG

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".

2026-07-173

name	hsg-rag-docs-and-writing
description	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.

HSG_RAG Docs and Writing

How this project documents itself: which document owns which fact, the house style for commits/PRs/checklists, and copy-paste templates. Facts here are current as of 2026-07-07.

When NOT to use this skill

Deciding whether a change is allowed or how it must be gated → hsg-rag-change-control
Recording the technical content of a resolved failure → hsg-rag-failure-archaeology (this skill only gives you its entry format)
Running or deploying anything → hsg-rag-run-and-operate
What counts as evidence for a claim → hsg-rag-validation-and-qa
External-facing messaging to stakeholders (IT, web team, DPO) → hsg-rag-stakeholder-comms

Document inventory — one home per fact

Document	Language	Purpose / owns
`README.md`	English	Public-facing overview: what the repo contains, setup, commands, Production Deployment section (live URL, auto-deploy behaviour).
`DEPLOYMENT_CHECKLIST.md`	German	The living go-live status document. Owns deployment state, open blockers, Go/No-Go criteria. Supersedes `docs/deploy_readiness_checklist.md`.
`AGENTS.md`	English	Agent onboarding: non-negotiables, environment traps, ops quick reference. Must stay in sync with actual rules.
`AUDIT_LATENCY_HALLUCINATIONS.md`	German	Post-mortem of the June 2026 overhaul. Its before → after metric table is the house standard for any future audit.
`docs/configuration_system_documentation.md`	—	Configuration surface reference.
`docs/datenschutz_deployment.md`	German	GDPR/data-protection decisions and retention rules.
`docs/user_profile_tracking.md`	—	User-profile mechanism.
`docs/weaviate_database_setup.md`	—	Weaviate cluster/collection setup.
`docs/chatbot_overhaul_plan.md`	English	Historical: the ten UX defects behind the June overhaul (believed fixed; do not re-litigate without new evidence).
`docs/deploy_readiness_checklist.md`	German	Superseded (2026-04-10 state). Do not update; do not cite as current.
`.claude/skills/`	English	This library. One skill = one directory with `SKILL.md`.

Rule: one home per fact. Other documents cross-reference; they do not duplicate. If a fact has no home, the checklist (deployment state) or a new docs/ file (everything else) gets it — not the README.

Language policy

Code, comments, commit messages, PR titles, AGENTS.md, skills: English.
Maintainer-facing status docs (checklist, GDPR docs, post-mortems): German is established; keep each document's existing language.
PR bodies: either language; existing PRs use German bodies with English titles.

House style

Commit messages

English, imperative, type: subject prefix (fix:, chore:, docs:, test:, tests: all occur; prefer fix|chore|docs|test). Body explains the mechanism and ends with verification numbers, not just intent. Real example (334da90):

fix: treat streamed tool-call responses as valid in model retry check

Under streaming, LangChain chunk aggregation concatenates finish_reason
across chunks ('tool_callstool_calls'), so the exact-match check
misclassified every tool-call response as empty. [...]

Check result.tool_calls directly instead of the fragile finish_reason
string. Verified live: first token 3.7s, total 6.7s (was 14.2s), no
retries, no blocking fallback.

Never add Co-Authored-By: Claude ... or similar AI-attribution trailers to commits or PRs (AGENTS.md non-negotiable #3).

PR bodies

Structure used in this repo (see PR #67, #68): ## Problem (with real log excerpts/evidence) → ## Fix (mechanism) → ## Verifikation/## Verification (concrete numbers, links to real workflow runs). A PR that changes behaviour without a verification section is out of style — and out of change control.

DEPLOYMENT_CHECKLIST.md conventions

Header line **Stand:** YYYY-MM-DD (what changed; ursprünglich ...) — update it with every substantive edit.
Checking off an item requires date + evidence inline, e.g.: - [x] Vor Release: RUN_LLM_EVAL=1 pytest ... → **31/31** (2026-07-07, 160 s)
Items that become obsolete are not deleted: strikethrough + reason, e.g. - [x] ~~HUGGING_FACE_API_KEY erneuern~~ — **entfällt** (2026-07-06): ...
Corrections keep history; never silently rewrite a checked entry.

Audits / post-mortems

Follow AUDIT_LATENCY_HALLUCINATIONS.md: lead with a Vorher → Nachher metric table, then Diagnose → Maßnahmen (checkboxed) → Ist-Architektur. Claims carry measured numbers ("31/31", "~6 s"), not adjectives.

Templates

Checklist check-off line:

- [x] <item text> (<YYYY-MM-DD>: <measured evidence, run link or numbers>)

Failure-archaeology entry (format contract with hsg-rag-failure-archaeology):

### <short name> (<YYYY-MM-DD resolved|open>)
- **Symptom:** <what was observed, verbatim log lines if possible>
- **Root cause:** <mechanism, one paragraph>
- **Evidence:** <commits, run IDs, measurements that pin the cause>
- **Status:** resolved in <PR/commit> | open | wont-fix because <reason>

PR body skeleton:

## Problem
<evidence: logs, numbers, user-visible effect>

## Fix
<mechanism of the change, why this and not the alternative>

## Verification
<commands run, numbers before/after, links to workflow runs>

Skill provenance section (every skill in this library ends with one):

## Provenance and maintenance

Facts verified <YYYY-MM-DD> against <source>. Re-verify:
- <claim>: `<one-line command>`

Sync obligations

When this happens	Also update
A working rule changes (gating, style, non-negotiable)	`AGENTS.md` + `hsg-rag-change-control` skill
A failure is investigated/resolved	`hsg-rag-failure-archaeology` + checklist entry if deploy-relevant
Deployment state changes (new infra, new workflow, item done)	`DEPLOYMENT_CHECKLIST.md` header + item, README Production section if user-visible
A volatile number is written anywhere (latency, counts, versions)	date-stamp it in place
A doc is superseded	mark it superseded at the top and link the successor; do not delete

Provenance and maintenance

Facts verified 2026-07-07 against the repo at commit d76d050. Re-verify:

Document inventory: ls docs/ *.md .claude/skills/
Commit style examples: git log --format='%h %s' -15 and git show -s --format=%B 334da90
Checklist conventions: head -5 DEPLOYMENT_CHECKLIST.md && grep -n '~~' DEPLOYMENT_CHECKLIST.md
PR body structure: gh pr view 67 --json body -q .body | head -30
No-AI-trailer rule: grep -n 'Co-Authored' AGENTS.md