mes_skills/skills/infra/ha-log-investigator/SKILL.md

name, description

name	description
ha-log-investigator	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.