Guide de génération Wiki Onboarding

Générez quatre documents d'intégration adaptés aux audiences dans un dossier onboarding/, chacun donnant à un stakeholder différent exactement la compréhension dont il a besoin.

Résolution du référentiel source (À FAIRE EN PREMIER)

Avant de générer des guides, vous DEVEZ déterminer le contexte du référentiel source :

1. Vérifiez la télécommande git : Exécutez git remote get-url origin pour détecter si une télécommande existe
2. Demandez à l'utilisateur : "S'agit-il d'un référentiel local uniquement, ou disposez-vous d'une URL de référentiel source (par exemple GitHub, Azure DevOps) ?"
   • URL de télécommande fournie → stockez comme REPO_URL, utilisez citations liées : [file:line](REPO_URL/blob/BRANCH/file#Lline)
   • Local uniquement → utilisez citations locales : (file_path:line_number)
3. Déterminez la branche par défaut : Exécutez git rev-parse --abbrev-ref HEAD
4. NE PROCÉDEZ PAS jusqu'à ce que le contexte du référentiel source soit résolu

Quand activer

• L'utilisateur demande des documents d'intégration ou des guides de démarrage
• L'utilisateur exécute la commande /deep-wiki:onboard
• L'utilisateur souhaite aider les nouveaux membres de l'équipe à comprendre une base de code

Structure de sortie

Générez un dossier onboarding/ avec ces fichiers :

onboarding/
├── index.md                    # Hub d'intégration — liens vers les 4 guides avec descriptions d'audiences
├── contributor-guide.md        # Pour les nouveaux contributeurs (suppose une expérience Python ou JS)
├── staff-engineer-guide.md     # Pour les ingénieurs staff/principaux
├── executive-guide.md          # Pour les responsables ingénierie VP/directeur
└── product-manager-guide.md    # Pour les chefs de produit et stakeholders non-ingénierie

index.md — Hub d'intégration

Une page d'accueil avec :

• Résumé d'un paragraphe du projet
• Tableau de sélection de guides :

Détection de langue

Analysez le référentiel pour chercher les fichiers de build afin de déterminer la langue principale pour les exemples de code :

• package.json / tsconfig.json → TypeScript/JavaScript
• *.csproj / *.sln → C# / .NET
• Cargo.toml → Rust
• pyproject.toml / setup.py / requirements.txt → Python
• go.mod → Go
• pom.xml / build.gradle → Java

Guide 1 : Guide Contributeur

Fichier : onboarding/contributor-guide.md Audience : Ingénieurs rejoignant le projet. Suppose une compétence en Python ou JavaScript et une expérience générale en génie logiciel. Longueur : 1000–2500 lignes. Progressif — chaque section s'appuie sur la précédente.

Sections requises

Partie I : Fondations (ignorez si le repo utilise Python ou JS)

1. {Langue primaire} pour ingénieurs Python/JS — Tableaux de comparaison syntaxique, modèle async, collections, système de types, gestion de paquets. Code concret côte à côte, JAMAIS de descriptions abstraites.
2. Essentiels {Framework primaire} — Comparez aux frameworks Python/JS équivalents (par ex. FastAPI, Express). Pipeline de requête, routage, injection de dépendances, config.

Partie II : Cette base de code 3. Ce que ce projet fait — Pitch d'ascenseur de 2-3 phrases 4. Structure du projet — Arborescence annotée (où vit quoi et pourquoi). Incluez un aperçu architecture graph TB. 5. Concepts clés — Terminologie spécifique au domaine expliquée avec exemples de code. Utilisez erDiagram pour le modèle de données. 6. Cycle de vie des requêtes — sequenceDiagram (avec autonumber) traçant une requête typique de bout en bout. 7. Motifs clés — Modèles "Si vous voulez ajouter X, suivez ce motif" avec code réel

Partie III : Devenir productif 8. Prérequis et configuration — Tableau : Outil, Version, Commande d'installation. Étape par étape avec sortie attendue à chaque étape. 9. Votre première tâche — Procédure complète d'ajout d'une fonctionnalité simple 10. Workflow de développement — Stratégie de branche, conventions de commit, processus PR. Utilisez le diagramme flowchart. 11. Exécution des tests — Tous les tests, fichier unique, test unique, commandes de couverture 12. Guide de débogage — Tableau de problèmes courants : Symptôme, Cause, Correction 13. Pièges courants — Erreurs que font tous les nouveaux contributeurs et comment les éviter

Appendices

• Glossaire (40+ termes)
• Référence fichiers clés — Tableau : Chemin, Objectif, Pourquoi c'est important, Source
• Carte de référence rapide — Aide-mémoire des commandes et motifs les plus utilisés

Règles

• Tous les exemples de code dans la langue primaire détectée
• Chaque commande doit être copiable avec sortie attendue
• Minimum 5 diagrammes Mermaid (architecture, ER, sequence, flowchart, state)
• Utilisez Mermaid pour les diagrammes de workflow (couleurs mode sombre) — ajoutez un bloc de commentaire <!-- Sources: ... --> après chacun
• Ancrez tous les énoncés dans du code réel — citez au format lié

Guide 2 : Guide Staff Engineer

Fichier : onboarding/staff-engineer-guide.md Audience : Ingénieurs staff/principaux qui ont besoin du « pourquoi » derrière chaque décision. Expérience profonde des systèmes, peut ne pas connaître la langue de ce repo. Longueur : 800–1200 lignes. Dense, opiné, architectural.

Sections requises

1. Résumé exécutif — Ce que le système est en un paragraphe dense. Ce qu'il possède vs délègue.
2. L'insight architectural principal — Le SEUL concept le plus important. Incluez du pseudocode dans une LANGUE DIFFÉRENTE du repo.
3. Architecture du système — Diagramme complet Mermaid graph TB. Appelez le « cœur » du système.
4. Modèle de domaine — Mermaid erDiagram des entités principales. Tableau d'invariants de données : Entité, Invariant, Appliqué par, Source.
5. Abstractions clés et interfaces — classDiagram montrant les abstractions porteuses de charge.
6. Cycle de vie des requêtes — sequenceDiagram (avec autonumber) montrant une requête typique de l'entrée à la réponse.
7. Transitions d'état — stateDiagram-v2 pour les entités avec cycles de vie significatifs.
8. Journal des décisions — Tableau : Décision, Alternatives considérées, Justification, Source.
9. Justification des dépendances — Tableau : Dépendance, Objectif, Ce qu'elle a remplacé, Source.
10. Flux et état des données — Comment les données se déplacent dans le système. Tableau de comparaison du stockage.
11. Modes de défaillance et gestion des erreurs — flowchart pour les chemins de propagation des erreurs.
12. Caractéristiques de performance — Goulots d'étranglement, limites de scalabilité, chemins chauds.
13. Modèle de sécurité — Auth, autorisation, limites de confiance, sensibilité des données.
14. Stratégie de test — Ce qui est testé, ce qui ne l'est pas, philosophie de test.
15. Dette technique connue — Tableau : Problème, Niveau de risque, Fichiers affectés, Source.
16. Où approfondir — Ordre de lecture recommandé des fichiers source, liens vers sections wiki.

Règles

• Utilisez pseudocode dans une langue différente pour expliquer les concepts
• Utilisez tableaux de comparaison pour cartographier les concepts non familiers (par ex. Task<T> = Awaitable[T])
• Prose dense avec tableaux, PAS de listes à puces superficielles
• Chaque énoncé appuyé par citation liée
• Minimum 5 diagrammes Mermaid (architecture, ER, class, sequence, state, flowchart)
• Chaque diagramme suivi d'un bloc de commentaire <!-- Sources: ... -->
• Utilisez les tableaux agressivement — décisions, dépendances, dette DOIVENT TOUS être des tableaux avec colonnes Source
• Concentrez-vous sur le POURQUOI des décisions, pas juste ce qui existe

Guide 3 : Guide Exécutif

Fichier : onboarding/executive-guide.md Audience : VP/directeur de l'ingénierie. A besoin d'un aperçu des capacités, d'une évaluation des risques et du contexte d'investissement — PAS de détails au niveau du code. Longueur : 400–800 lignes. Stratégique, concis, orienté vers les décisions.

Sections requises

1. Aperçu du système — Ce qu'il fait, qui l'utilise, valeur commerciale en 2-3 phrases
2. Carte des capacités — Tableau : Capacité, Statut (Construit/Partiel/Planifié), Maturité, Dépendances. Ce que le système peut et ne peut pas faire aujourd'hui.
3. Architecture en un coup d'œil — Diagramme Mermaid graph LR haut niveau. Services, magasins de données, intégrations externes — PAS de détails de code interne. Concentrez-vous sur les unités de déploiement et les limites d'équipe.
4. Topologie d'équipe — Quelle équipe/personne possède quels composants. Tableau : Composant, Propriétaire, Criticité, Bus Factor.
5. Thèse d'investissement technologique — Pourquoi ces technologies ont été choisies. Tableau : Technologie, Objectif, Alternatives considérées, Niveau de risque.
6. Évaluation des risques — Tableau : Risque, Probabilité, Impact, Atténuation, Propriétaire. Couvrez fiabilité, sécurité, scalabilité, conformité.
7. Modèle de coûts et scalabilité — Comment les coûts s'ajustent à l'utilisation. Quels sont les goulots d'étranglement. Quand le prochain investissement de scalabilité est nécessaire.
8. Carte des dépendances — graph TB montrant les dépendances externes critiques. Tableau : Dépendance, Type (Service/Bibliothèque/Plateforme), Risque si indisponible.
9. Métriques clés et observabilité — Ce qui est mesuré, quels tableaux de bord existent, couverture des alertes. Tableau : Métrique, Valeur actuelle, Cible, Source.
10. Alignement feuille de route — Workstreams d'ingénierie cartographiés aux priorités commerciales. Ce qui est en cours, ce qui est planifié, ce qui est bloqué.
11. Résumé de la dette technique — Top 5 des éléments de dette avec impact commercial. Tableau : Problème, Impact commercial, Effort pour corriger, Priorité.
12. Recommandations — 3-5 recommandations actionnables pour le prochain trimestre, priorisées par impact.

Règles

• AUCUN extrait de code — ce guide s'adresse aux responsables de l'ingénierie, pas aux codeurs
• Diagrammes au niveau service/équipe, pas au niveau classe/fonction
• Chaque énoncé appuyé par des preuves — citez les sections wiki, docs architecture ou fichiers source
• Minimum 3 diagrammes Mermaid (aperçu architecture, carte dépendances, capacité/feuille de route)
• Tableaux pour chaque constatation structurée — ce public lit des tableaux, pas de la prose
• Langage métier — traduisez les concepts techniques en impact (fiabilité, vélocité, coût, risque)

Guide 4 : Guide Chef de Produit

Fichier : onboarding/product-manager-guide.md Audience : Chefs de produit et stakeholders non-ingénierie. Besoin de comprendre ce que fait le système, ce qui est possible et où se trouvent les limites — PAS comment c'est construit. Longueur : 400–800 lignes. Centré utilisateur, orienté fonctionnalités, conscient des contraintes.

Sections requises

1. Ce que ce système fait — Pitch d'ascenseur de 2-3 phrases en langage utilisateur (sans jargon)
2. Carte des parcours utilisateur — Diagramme Mermaid graph LR ou journey montrant les flux utilisateur primaires dans le système
3. Carte des capacités fonctionnelles — Tableau : Fonctionnalité, Statut (Live/Bêta/Planifié/Impossible), Comportement utilisateur, Limitations. Cartographie complète de ce qui est construit et ce qui ne l'est pas.
4. Modèle de données (vue produit) — Diagramme Mermaid erDiagram simplifié montrant les entités avec lesquelles les utilisateurs interagissent. Expliquez en termes commerciaux (par ex. « Un Projet a plusieurs Documents » et non « relation FK »).
5. Configuration et feature flags — Tableau : Flag/Config, Ce qu'elle contrôle, Par défaut, Qui peut la changer. Ce qui peut être basculé sans travail d'ingénierie.
6. Capacités API — Quelles intégrations sont possibles. Tableau : Capacité, Endpoint/Méthode, Authentification, Limites de débit. Écrit pour les partenaires d'intégration, pas pour les développeurs.
7. Performance et SLA — Temps de réponse, limites de débit, objectifs de disponibilité. Tableau : Opération, Latence attendue, Limite de débit, SLA actuel.
8. Limitations et contraintes connues — Liste honnête de ce que le système ne peut pas faire ou fait mal. Tableau : Limitation, Impact utilisateur, Contournement, Correction planifiée.
9. Données et confidentialité — Quelles données sont collectées, où elles sont stockées, politiques de rétention, statut de conformité. Tableau : Type de données, Lieu de stockage, Rétention, Conformité.
10. Glossaire — Termes de domaine expliqués en langage clair (pas de jargon d'ingénierie)
11. FAQ — 10+ questions courantes qu'un chef de produit se poserait, répondues brièvement

Règles

• ZÉRO jargon d'ingénierie — pas de « middleware », « injection de dépendances », « ORM ». Utilisez le langage clair.
• Cadrage centré utilisateur — décrivez tout en termes de ce que les utilisateurs expérimentent, pas de comment le code fonctionne
• Minimum 3 diagrammes Mermaid (parcours utilisateur, modèle de données, carte fonctionnalités/aperçu capacités)
• Tableaux pour chaque constatation structurée — les chefs de produit scannent les tableaux, pas la prose
• Si un concept technique doit être mentionné, expliquez-le en une phrase (par ex. « Feature flags — bascules qui nous permettent d'activer/désactiver des fonctionnalités sans déployer du code »)
• Chaque énoncé ancré dans des preuves — citez les sections wiki ou fichiers source pour vérification

Règles de diagramme Mermaid (TOUS les guides)

TOUS les diagrammes doivent utiliser les couleurs en mode sombre :

• Remplissages de nœuds : #2d333b, bordures : #6d5dfc, texte : #e6edf3
• Arrière-plans subgraph : #161b22, bordures : #30363d
• Lignes : #8b949e
• En cas d'utilisation de directives style inline, utilisez des remplissages sombres avec ,color:#e6edf3
• N'utilisez PAS <br/> dans les étiquettes Mermaid (utilisez <br> ou sauts de ligne)

Validation

Après la génération de chaque guide, vérifiez :

• Tous les chemins de fichiers mentionnés existent réellement dans le repo
• Tous les noms de classe/méthode sont exacts (pas hallucines)
• Les diagrammes Mermaid se rendent (pas d'erreurs syntaxiques)
• Pas de balises nues de type HTML (génériques comme List<T>) en dehors des clôtures de code — enveloppez dans des backticks
• Chaque guide est approprié pour son audience — pas de code dans les guides Exécutif/Chef de Produit