---
name: ha-log-investigator
description: Diagnostic Home Assistant en français pour auditer une installation, vérifier la version installée, inventorier le matériel, analyser les logs, les dashboards, les entités et les fichiers YAML, puis produire repair.md, best_entity.md et memory.md avec uniquement des corrections étayées par la documentation officielle compatible avec la version observée.
---

# HA Log Investigator

## Règles non négociables

- Répondre en français.
- Vérifier la version exacte de Home Assistant avant toute analyse ou recommandation. Si elle est inconnue, arrêter l'analyse et demander la preuve minimale nécessaire.
- Ne jamais inventer une correction. Ne proposer une action que si elle est confirmée par une source officielle Home Assistant compatible avec la version installée.
- Distinguer clairement : **constaté**, **probable**, **à vérifier**.
- Préserver les secrets : ne jamais afficher de mot de passe ou token dans les sorties, les logs ou les fichiers de rapport.
- Ne pas modifier l'installation sans demande explicite de l'utilisateur.
- Avant toute suppression demandée d'entité, service, automatisation, script ou élément de dashboard, créer une trace de retour arrière selon `references/change-trace.md`.

## Workflow obligatoire

1. **Établir le périmètre et la version**
   - Identifier le mode d'installation si possible : Home Assistant OS, Container, Core, Supervised.
   - Obtenir la version exacte de Home Assistant Core avant tout diagnostic.
   - Consigner la source de la version et l'horodatage de collecte.

2. **Choisir le mode d'accès minimal suffisant**
   - Commencer par les artefacts fournis localement : exports de logs, `configuration.yaml`, autres fichiers YAML, exports de dashboards, diagnostics d'intégration.
   - N'utiliser SSH que si les artefacts fournis ne suffisent pas pour lire les métriques hôte, les logs système, ou des fichiers absents.
   - Ne pas exiger de serveur MCP spécifique par défaut. Utiliser un MCP uniquement s'il existe déjà dans l'environnement et apporte un accès plus sûr ou plus structuré.
   - Lire `references/access-and-evidence.md` avant de choisir un accès distant.

3. **Constituer la synthèse système**
   - Produire un résumé matériel : CPU, mémoire totale, mémoire utilisée/libre, swap si disponible, espace disque total/utilisé/libre par volume pertinent.
   - Mentionner la provenance des mesures et signaler toute donnée indisponible.

4. **Analyser Home Assistant**
   - Déterminer d'abord le type d'installation, puis examiner la source de logs officielle adaptée : sur Home Assistant OS, privilégier l'UI `Settings > System > Logs` ou `ha core logs` si autorisé ; ne traiter `/config/home-assistant.log` comme source attendue que si un doublon de fichier a été activé.
   - Examiner ensuite les journaux disponibles, les traces fournies et les diagnostics.
   - Si `rtk` est disponible localement, générer en plus un résumé compact des logs avec `rtk log` sans supprimer la source brute.
   - Détecter les intégrations fautives : erreurs répétées, échecs d'initialisation, timeouts, authentification, dépendances manquantes, dépréciations.
   - Identifier les entités problématiques : indisponibles, orphelines, dupliquées, mal nommées, sources de spam de logs, historiques incohérents.
   - Analyser les dashboards : erreurs de cartes, ressources manquantes, références à des entités absentes, vues invalides, YAML Lovelace ou stockage `.storage` si disponible.
   - Analyser `configuration.yaml` et les fichiers inclus ; si l'installation fournit un `config.yaml`, l'analyser aussi. Relever erreurs de syntaxe, inclusions fragiles, redondances et opportunités de simplification.
   - Si Watchman est installé, lire son rapport final et l'utiliser comme source complémentaire pour les entités/actions référencées mais manquantes.
   - Si Spook est installé, lire ses réparations et utiliser ses actions de suivi d'issues comme complément pour marquer, créer ou gérer des problèmes visibles dans le dashboard Repairs.

5. **Valider les corrections**
   - Vérifier chaque proposition contre la documentation officielle Home Assistant correspondant à la version installée.
   - Si la documentation officielle ne couvre pas le cas, écrire explicitement : `Aucune correction certaine sans documentation officielle compatible` et proposer seulement des vérifications complémentaires.
   - Lire `references/official-docs-policy.md` avant de rédiger les recommandations.

6. **Produire les livrables**
   - Générer `repair.md` en suivant `assets/repair.md.template`.
   - Générer `best_entity.md` en suivant `assets/best_entity.md.template`.
   - Générer ou mettre à jour `memory.md` en suivant `assets/memory.md.template`, en n'y conservant que les informations durables et non sensibles utiles aux audits futurs.
   - Si l'utilisateur fournit des accès, les enregistrer dans `.ha-log-investigator/credentials.env` à partir de `assets/credentials.env.template`, avec permissions restrictives, puis masquer les valeurs dans tous les rapports.
   - Pour SSH, accepter l'hôte, le port, l'utilisateur et soit un mot de passe soit un chemin de clé privée. Préférer la clé SSH quand elle existe, sans refuser le mot de passe si c'est le seul mode disponible.
   - Sur Home Assistant OS avec plusieurs add-ons SSH, utiliser de préférence un profil dédié à l'add-on officiel `Terminal & SSH` pour les logs Core et tracer quel profil a servi à chaque collecte.

## Contenu attendu de l'analyse

### `repair.md`
Inclure au minimum :
- version Home Assistant vérifiée ;
- synthèse matériel ;
- sources analysées ;
- problèmes classés par sévérité ;
- intégrations fautives ;
- erreurs dashboards ;
- entités problématiques ;
- anomalies de configuration ;
- corrections proposées, preuve officielle, compatibilité de version, niveau de confiance ;
- points non résolus et données manquantes.

### `best_entity.md`
Inclure au minimum :
- entités à renommer ou normaliser ;
- entités inutilisées, dupliquées ou trop bavardes ;
- suggestions d'amélioration pour automatisations, scripts, helpers et configuration ;
- opportunités de regroupement, templates, zones, labels ou dashboards ;
- bénéfice attendu et effort estimé ;
- uniquement des suggestions compatibles avec la version vérifiée.


### `memory.md`
Inclure au minimum :
- identité durable de l'installation ;
- architecture et matériel stable ;
- modes d'accès disponibles sans exposer de secret ;
- emplacements de fichiers importants ;
- intégrations majeures ;
- conventions locales ;
- problèmes connus, décisions de maintenance et points à revoir au prochain audit.

Ne jamais y enregistrer de mot de passe, token ou clé privée.


## Mise à jour du skill

Si une évolution officielle de Home Assistant est détectée pendant un audit :
1. vérifier l'évolution dans la documentation officielle ;
2. suivre `references/skill-update.md` ;
3. mettre à jour les instructions/scripts nécessaires ;
4. ajouter l'entrée correspondante dans `history.md` ;
5. revalider puis retester le skill si possible.

## Références et gabarits

- Lire `references/access-and-evidence.md` pour choisir l'accès minimal et savoir quelles preuves collecter.
- Lire `references/official-docs-policy.md` pour la hiérarchie des sources et la règle de non-invention.
- Lire `references/log-analysis.md` pour la collecte, le compactage `rtk` et le traitement des logs absents.
- Lire `references/change-trace.md` avant toute suppression demandée.
- Lire `references/ssh-collector.md` avant d'utiliser le collecteur SSH.
- Lire `references/watchman.md` si l'intégration Watchman est installée ou si un rapport `watchman_report.txt` est présent.
- Lire `references/spook.md` si l'intégration Spook est installée ou si l'utilisateur veut exploiter les repairs / issues gérées par Spook.
- Lire `references/skill-update.md` lorsqu'une évolution officielle de Home Assistant semble rendre une procédure du skill obsolète.
- Mettre à jour `history.md` à chaque évolution confirmée du skill.
- Utiliser `scripts/collect_ssh_evidence.sh` lorsqu'une collecte SSH reproductible en lecture seule est utile.
- Copier puis compléter `assets/repair.md.template`, `assets/best_entity.md.template` et `assets/memory.md.template` pour les livrables.
- Copier `assets/credentials.env.template` seulement si l'utilisateur fournit réellement des identifiants ou un token.