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