Orchestrator/bahn/teamlandkarte-mcp/.github/prompts/debug-matching.prompt.md

description

description
Debug matching issues — investigate why capacity matching produces unexpected results (wrong scores, missing candidates, expired searches).

$ARGUMENTS

Debugging Matching Issues

Common Issues

1. Unexpected scores (too high/low)

• Check config.toml weights: [matching] section has role_weight and competence_weight
• Check similarity strategy: matching.similarity.use_bm25_search (BM25 vs embeddings)
• BM25 scores 0.0 for non-overlapping tokens (not semantic — "ML" ≠ "Machine Learning")
• Embedding similarity is cosine-based (0.0–1.0 range)

2. Missing candidates

• Check availability filtering: date_start/date_end may exclude valid candidates
• Check is_fully_available filter — partial overlap candidates are excluded
• Verify the candidate has a published capacity in the database

3. Expired/invalid search sessions

• Search cache TTL: 60 minutes (configurable in [cache])
• If status=unknown_or_expired: rerun find_matching_capacities(...) for fresh results
• Never retry with a guessed search_id

4. Embedding failures

• Check Azure OpenAI connectivity and API key in .env
• Check azure_openai.embedding_batch_size in config (default: 128)
• Failure is strict: no heuristic fallback

Diagnostic Steps

1. Check config: cat config.toml — verify weights, thresholds, similarity strategy
2. Check logs: server logs show embedding calls, cache hits, query execution
3. Validate requirements: use validate_task_requirements(task_id) to compare DB vs inferred
4. Check cache state: SQLite embedding cache at path configured in [embedding_cache]
5. Run with verbose: uv run pytest -v tests/test_similarity.py for similarity logic tests

Key Files

• src/teamlandkarte_mcp/matching/scorer.py — scoring logic
• src/teamlandkarte_mcp/matching/similarity.py — similarity computation
• src/teamlandkarte_mcp/matching/matcher.py — orchestration
• src/teamlandkarte_mcp/cache/ — all cache layers
• config.toml — runtime configuration