Jamie-BitFlight/transcript-analysis

Analyse de Transcriptions

Analysez les transcriptions de sessions Claude Code au format JSONL pour détecter les anti-patrons, les inefficacités et les opportunités d'amélioration des workflows.

Emplacement des Données

Les transcriptions se trouvent sous ~/.claude/projects/ dans des répertoires spécifiques à chaque projet, nommés d'après le chemin du projet (avec des tirets remplaçant les slashes).

Rôle de DuckDB : Chargez la référence complète des champs/chemins depuis kaizen-analysis via get_transcript_jsonl_schema ou MCP resources/read kaizen://session-log/schema, puis utilisez kaizen-duckdb execute_query pour exécuter n'importe quelle requête SQL DuckDB sur ces fichiers (voir Modèles de Requêtes DuckDB pour des exemples et le workflow de requêtes arbitraires). L'historique des sessions reste au format JSONL sur le disque. Règles de chemin pour le MCP DuckDB (chemins absolus, pas de ~ dans SQL).

~/.claude/projects/{project-key}/
├── {uuid}.jsonl              # Transcriptions principales de session
├── agent-{id}.jsonl          # Transcriptions d'agents orphelins
└── {uuid}/
    ├── subagents/
    │   └── agent-{id}.jsonl  # Transcriptions de sous-agents
    └── tool-results/
        └── {tool-use-id}.txt # Sorties de tâches asynchrones

Types d'Enregistrements JSONL

Chaque ligne JSONL est un objet JSON identifié par le champ type.

Principaux types d'enregistrements pour l'analyse :

• assistant — Tours de réponse du LLM contenant des appels d'outils et du texte
• user — Entrée humaine et résultats d'outils
• system — Événements de métadonnées (stop_hook_summary, turn_duration, compact_boundary, api_error, local_command)
• progress — Exécution de hooks et streaming de sous-agents
• file-history-snapshot — Suivi des éditions de fichiers
• summary — Titre/résumé de la session

Pour les détails complets du schéma, y compris les structures JSON pour chaque type d'enregistrement, voir Référence du Schéma JSONL.

Catalogue de Signaux

Chaque dimension d'analyse ci-dessous a sa propre méthodologie d'extraction.

1. Détection de Mauvais Usage des Outils

Extrayez de assistant.message.content[] où name == "Bash". Analysez input.command pour les motifs d'opérations sur fichiers qui devraient utiliser les outils intégrés. Pour les requêtes d'extraction SQL, voir Modèles de Requêtes DuckDB.

Analysez les blocs tool_use pour les commandes Bash correspondant à :

• grep → devrait utiliser l'outil Grep
• find -name → devrait utiliser l'outil Glob
• cat, head, tail → devrait utiliser l'outil Read
• ls → devrait utiliser Glob ou Bash(ls) avec description
• sed, awk → devrait utiliser l'outil Edit

Exclure les utilisations légitimes dans des pipelines (git ... | grep, uv run ... | head).

2. Erreurs Répétées

Extrayez des résultats d'outils où is_error: true. Classez les types d'erreurs :

• "File has not been read yet" — Anti-patron Edit-avant-Read
• "String to replace not found" — Cible d'Edit obsolète
• "User denied tool use" — Problème de permission/confiance
• Échecs de hook pre-commit (code de sortie 1)
• Binaire manquant / commande introuvable

3. Opportunités d'Outillage Manquant

Identifiez les workflows manuels multi-étapes qui se répètent entre sessions via une analyse de trigrammes de séquences d'outils. Les trigrammes à haute fréquence comme Bash → Bash → Bash ou Read → Read → Read suggèrent des scripts ou compétences manquants.

4. Schémas de Délégation de Sous-Agents

Extrayez des blocs d'utilisation de l'outil Task. Suivez subagent_type, description, model. Signalez quand general-purpose est utilisé alors qu'un agent spécialisé existe.

5. Analyse du Plus Court Chemin

Comparez les tentatives réussies et échouées pour le même objectif. Mesurez le nombre d'appels d'outils entre l'énoncé de l'objectif (tour utilisateur) et le résultat réussi (dernier tour assistant). Une variance élevée entre sessions pour des objectifs similaires indique des étapes inutiles.

6. Détection de Fausses Pistes

Suivez les branches d'investigation abandonnées. Signal : une séquence d'appels Read/Grep/Bash sur un sujet suivie de compact_boundary ou d'un changement de direction sans résolution. La fréquence inter-sessions des mêmes chemins abandonnés révèle des fausses pistes systématiques.

7. Interruptions Système

Extrayez system.compact_boundary, system.api_error et les événements progress liés aux hooks. Cartographiez leur position par rapport au travail actif pour identifier quand les processus système ont fait dérailler les chemins d'exécution corrects.

8. Hooks Manquants

Identifiez les corrections manuelles qui se répètent entre sessions. Lorsque la même correction apparaît 3 fois ou plus, c'est un candidat pour une prévention automatisée via un hook PreToolUse (refus + redirection) ou un hook SubagentStart (injection de contexte).

9. Requêtes SQL DuckDB

Utilisez get_transcript_jsonl_schema de kaizen-analysis ou la ressource kaizen://session-log/schema pour la référence complète des chemins, puis kaizen-duckdb execute_query pour n'importe quelle requête SQL sur les JSONL (read_ndjson_auto avec chemins absolus). Vous n'êtes pas limité aux requêtes du livre de recettes.

Pour le workflow de requêtes arbitraires et des exemples, voir Modèles de Requêtes DuckDB.

Méthodologie de Process Mining

Utilisez les outils du serveur MCP kaizen-analysis pour les analyses que SQL ne peut pas exprimer :

• extract_tool_sequences — Convertir les JSONL en tableaux ordonnés d'appels d'outils par session
• discover_process_model — Modèle de transition léger sur les séquences d'appels d'outils
• check_conformance — Comparer les sessions à un modèle de processus de référence
• find_frequent_patterns — Extraction de motifs séquentiels avec PrefixSpan
• cluster_sessions — Regroupement de traces par similarité comportementale

Workflow d'Analyse

flowchart TD
    Start([Recevoir la tâche d'analyse]) --> Scope{Portée définie ?}
    Scope -->|--project flag| Project[Filtrer sur les transcriptions du projet]
    Scope -->|Pas de flag| Default[Utiliser le projet courant]
    Project --> Discover[SQL — compter les sessions, plage de dates, types d'enregistrements]
    Default --> Discover
    Discover --> Dimensions{Quelles dimensions ?}
    Dimensions -->|Toutes| RunAll[Exécuter toutes les dimensions]
    Dimensions -->|Spécifiées| RunSelected[Exécuter les dimensions sélectionnées]
    RunAll --> Aggregate[Agréger les résultats]
    RunSelected --> Aggregate
    Aggregate --> Write[Écrire dans .planning/kaizen/analysis-DATE.md]

Format de Sortie

Écrivez les résultats de l'analyse dans .planning/kaizen/ sous forme de Markdown structuré avec :

• ID de session et date pour chaque résultat
• Sévérité (critique / avertissement / info)
• Preuve — chemins et valeurs exacts des champs JSON
• Fréquence — combien de sessions présentent le motif
• Type de recommandation — hook, correction de compétence, correction de prompt d'agent, mise à jour de CLAUDE.md