BuildStory

Que fait BuildStory ?

BuildStory aide une personne à voir comment un projet a été construit, pas seulement ce qui a été livré. Il reconstruit un petit ensemble de points de basculement, met en évidence les retravaux répétés et les pertes de temps probables, examine l'alignement humain-IA étayé par des preuves lorsque les transcripts sont autorisés, et transforme les preuves en leçons et en matériel de carrière.

Principes non-négociables

• Traiter les logs Git et les sessions comme des preuves, pas comme de la lecture de pensée. Étiqueter les inférences et leur niveau de confiance.
• Commencer par l'histoire du projet. Conserver les nombres bruts de commits, l'historique complet et les calculs numériques comme preuves à l'appui.
• Montrer le rythme du projet comme une activité observable, jamais comme une mesure de diligence ou de productivité. Utiliser "jour le plus actif", pas "jour le plus dur".
• Sélectionner au maximum sept points de basculement par défaut. Un log Git complet est une preuve, pas un récit.
• Ne jamais réduire le projet à un seul score total. Présenter un profil irrégulier sur plusieurs dimensions.
• Ne pas assimiler itération et gaspillage. Appeler les schémas suspects des "candidats boucle" jusqu'à ce que la preuve ou l'utilisateur les confirme.
• Préférer un aperçu du parcours au niveau du thème plutôt qu'une statistique au niveau du fichier. Un chemin et un taux de remaniement sont des preuves ; ils ne sont pas la conclusion.
• Classifier le travail répété uniquement comme blocked-loop, necessary-exploration ou direction-change provisoire, puis demander à l'utilisateur d'en confirmer la cause.
• Ne pas inventer d'impact commercial, de responsabilité, de taille d'équipe, de gains de performance ou de métriques de CV.
• Examiner l'interaction, ne jamais noter ou diagnostiquer la capacité de communication de l'utilisateur. Ne pas calculer un score total de qualité de prompt.
• Un prompt répété n'est pas une preuve de formulation peu claire. Exiger une chaîne utilisateur → assistant → correction utilisateur dans la même session avant de créer un aperçu de communication.
• Garder distincts les échecs d'exécution de l'IA, les décalages de sens des termes, l'évolution des exigences et les preuves insuffisantes. Ne jamais attribuer par défaut à l'utilisateur.
• Traiter les commits Git proches d'une clarification comme des preuves voisines, pas comme la preuve que la clarification a causé le commit.
• Lire uniquement le projet actuel par défaut. Demander avant de lire des fichiers de session en dehors de l'espace de travail autorisé.
• Garder l'analyse en local sauf si l'utilisateur demande explicitement un service externe.
• Ne jamais télécharger ou reproduire un transcript complet. Ne conserver que les courts extraits nécessaires pour expliquer une conclusion.
• Ne pas modifier les fichiers sources du projet. Écrire les résultats dans un répertoire de sortie dédié.

Workflow par défaut

1. Établir le périmètre

Identifier la racine du dépôt et l'objectif de l'utilisateur. Par défaut, utiliser la branche courante et tout l'historique Git accessible depuis HEAD.

Utiliser les transcripts de session uniquement lorsqu'ils sont déjà fournis ou que l'utilisateur autorise leurs chemins. Les rapports basés uniquement sur Git sont utiles mais doivent marquer les estimations de temps et les conclusions au niveau de l'intention comme étant de moindre confiance.

2. Collecter les preuves déterministes

Exécuter l'analyseur fourni :

python3 <chemin-dossier-skill>/scripts/build_story.py <chemin-depot> \
  --output <chemin-depot>/rapport-build-story \
  --language <zh|en>

Ajouter une ou plusieurs sources de transcript lorsqu'elles sont autorisées :

python3 <chemin-dossier-skill>/scripts/build_story.py <chemin-depot> \
  --session <fichier-ou-dossier-session-autorise> \
  --output <chemin-depot>/rapport-build-story \
  --language <zh|en>

Lorsqu'un contexte confirmé par l'utilisateur est disponible, l'enregistrer dans le répertoire de sortie du rapport et réexécuter avec --context :

{
  "zh": {
    "role": "你的真实职责",
    "outcome": "最终带来的真实结果",
    "key_decision": "最能代表能力的关键决定",
    "summary": "一句话项目故事",
    "resume_bullets": ["经过确认的简历要点"],
    "insight_confirmations": {
      "chemin:src/sync.py": {
        "classification": "direction-change",
        "reason": "自动同步违背了面向小白的简单性。",
        "lesson": "当一个功能持续引入恢复机制时，先重新判断它是否值得存在。"
      }
    },
    "communication_confirmations": {
      "communication:exemple-id": {
        "attribution": "ai-ignored-explicit-requirement",
        "reason": "原始要求已经明确说明必须保留语言切换。",
        "analysis": "这次更像 AI 执行遗漏，而不是用户需要把话说得更长。",
        "lesson": "明确边界仍被遗漏时，先检查 AI 执行。"
      }
    },
    "translations": {
      "Initialize project": "初始化项目",
      "Add the requested feature": "加入用户要求的功能"
    }
  },
  "en": {
    "role": "your real responsibility",
    "outcome": "the verified result",
    "key_decision": "the decision that best demonstrates your ability",
    "summary": "the one-line project story",
    "resume_bullets": ["a confirmed resume bullet"]
  }
}

python3 <chemin-dossier-skill>/scripts/build_story.py <chemin-depot> \
  --context <chemin-depot>/rapport-build-story/context.json \
  --output <chemin-depot>/rapport-build-story \
  --language <zh|en>

Le script génère un rapport par défaut ainsi que des variantes en anglais et en chinois :

• evidence.json : preuves lisibles par machine et métriques transparentes
• report.md : rapport texte portable
• report.html : rapport visuel autonome avec un bouton EN / 中文
• evidence.en.json, report.en.md, report.en.html : sorties en anglais
• evidence.zh.json, report.zh.md, report.zh.html : sorties en chinois

3. Inspecter les preuves avant de raconter

Lire evidence.json et vérifier :

• les journey_insights en premier : leur sujet, classification provisoire, chaîne de preuves, niveau de confiance et question de confirmation ;
• les communication_insights lorsque les transcripts sont autorisés : pas plus de trois fiches, chacune basée sur une demande utilisateur ordonnée, une réponse de l'assistant, et une correction ultérieure de l'utilisateur ;
• chaque attribution de communication reste distincte : information clarifiée plus tard, IA a ignoré une exigence explicite, sens du terme différent, exigence a évolué, ou preuves insuffisantes ;
• les sources de données et les limitations énoncées ;
• les dates du projet, le nombre de commits, les auteurs et le nombre de fichiers ;
• si l'histoire de l'écran d'accueil est étayée par les points de basculement sélectionnés ;
• si la durée du projet, les jours actifs, la plus longue série et le jour le plus actif correspondent aux preuves datées sous-jacentes ;
• les revert explicites par rapport aux boucles de remaniement élevé inférées ;
• si les estimations de temps proviennent de Git ou de sessions horodatées ;
• la preuve et le niveau de confiance derrière chaque score de dimension.

Ne pas commencer la conversation avec src/foo.py, le nombre de commits ou les pourcentages de remaniement. Traduire l'aperçu le plus fort en langage simple d'abord :

1. ce que l'utilisateur semble avoir essayé ;
2. si cela ressemble actuellement à une boucle bloquée, une exploration nécessaire ou un changement de direction ;
3. quels commits soutiennent cette interprétation ;
4. le seul fait humain manquant qui pourrait changer la conclusion.

Si les données contredisent la description de l'utilisateur, montrer la divergence et demander plutôt que de choisir silencieusement une version.

Pour un rapport en chinois, inspecter les titres des points de basculement visibles et les extraits de conversation. Si le matériel source est dans une autre langue, ajouter des entrées source-à-chinois exactes sous zh.translations et réexécuter. Conserver le texte original dans les données de preuve, mais ne pas faire lire à l'utilisateur une histoire de développement en anglais dans une interface chinoise.

Lorsque des transcripts autorisés existent, utiliser la courte demande utilisateur et la réponse IA attachées à chaque point de basculement. Préférer ce dialogue lisible par l'humain plutôt que de présenter un sujet de commit comme l'histoire complète.

4. Confirmer le parcours avant d'écrire le résultat

Poser au maximum trois questions de confirmation au total. Les choisir parmi les journey_insights non confirmés de plus haute confiance et, uniquement lorsque l'utilisateur a demandé une revue de communication, un ou deux communication_insights. Ne pas demander à l'utilisateur de modifier manuellement l'un ou l'autre objet de confirmation. Après la réponse de l'utilisateur, écrire la confirmation du parcours dans insight_confirmations ou la confirmation de communication dans communication_confirmations, réexécuter l'analyseur et vérifier que le rapport montre l'interprétation confirmée.

Ce n'est qu'après la confirmation du parcours que l'on demande le contexte de carrière restant. Ne pas transformer le workflow en un entretien. Les faits manquants habituels sont :

1. Quelle était la véritable responsabilité de l'utilisateur ?
2. Quel résultat le projet a-t-il créé pour l'utilisateur ou pour lui-même ?
3. Quelle décision démontre le mieux la capacité de l'utilisateur ?

Ignorer les questions dont les réponses sont déjà documentées dans le dépôt.

Pour les résultats de carrière, portfolio, réalisations ou entretien, ne pas laisser ces réponses comme un simple contexte de chat. Les enregistrer dans context.json, réexécuter l'analyseur et vérifier le matériel réutilisable résultant. Le rapport HTML est l'artefact durable, pas un substitut à la conversation de confirmation.

5. Produire l'histoire demandée

Utiliser les preuves pour un ou plusieurs de ces résultats :

• Rétrospective de projet : chronologie, points de basculement, frictions, leçons, changements pour la prochaine itération.
• Revue de communication : formulation originale, interprétation de l'assistant, correction ultérieure, attribution neutre, et, uniquement lorsque cela est étayé, une réécriture prête à copier et un modèle réutilisable. Montrer au maximum trois fiches et ne jamais donner de score de prompt.
• Étude de cas pour portfolio : problème, contraintes, décisions, implémentation, validation, résultat.
• Éléments de CV : action + périmètre + méthode + résultat vérifié. Laisser un espace réservé explicite lorsque l'impact est inconnu.
• Histoire pour entretien : structure STAR basée sur les commits, les diffs, les tests, les versions et le contexte confirmé par l'utilisateur.
• Enregistrement de réalisation : fiches de preuves durables qui expliquent ce que l'utilisateur a réellement fait.

Lire references/narrative-guide.md lors de la production d'écrits de carrière ou de portfolio. Lire references/methodology.md lors de l'explication des scores, des estimations de temps ou de la détection de boucles.

Barre de qualité des résultats

Un rapport BuildStory terminé doit permettre à l'utilisateur de répondre :

1. Quelle est l'histoire en une phrase de ce projet ?
2. Sur quelle période calendaire le travail observable a-t-il eu lieu, combien de jours, et que s'est-il passé le jour le plus actif ?
3. Quels cinq à sept virages ont changé sa direction, son risque, sa compréhension ou son état de livraison ?
4. Où le travail a-t-il bouclé ou inversé à plusieurs reprises ?
5. Chaque zone répétée était-elle une boucle bloquée, une exploration nécessaire ou un changement de direction, et qu'est-ce qui doit encore être confirmé ?
6. Quelles zones ont absorbé le plus d'attention, et quelle est la confiance dans cette estimation ?
7. Qu'est-ce que l'utilisateur a démontré avoir appris ou amélioré ?
8. Quelle réalisation crédible peut être réutilisée dans un CV, un portfolio, un entretien ou un dossier personnel ?
9. Quels détails ne sont devenus clairs qu'après que l'IA a déjà agi, comment la cause doit-elle être attribuée, et qu'est-ce qui pourrait être dit plus tôt la prochaine fois ?

Si les preuves disponibles ne peuvent pas répondre à l'une de ces questions, indiquer ce qui manque. Une petite histoire honnête est meilleure qu'une histoire impressionnante mais fictive.