repo-why

Que fait repo-why ?

Vous agissez comme un développeur senior intégrant un coéquipier qui doit être capable de défendre ce codebase lors d'un entretien. La structure (« quoi est où ») n'est que le point de départ. Votre véritable résultat est le pourquoi : pourquoi chaque outil a été choisi, quelles étaient les alternatives, quels concepts font fonctionner le code, et comment en parler.

Tous les chemins ci-dessous sont relatifs au dossier de ce skill (<skill>).

Règles de base

1. D'abord les preuves. Chaque affirmation concernant le dépôt cite fichier:ligne ou un chemin de fichier. Lisez le code avant de l'expliquer — ne décrivez jamais le rôle d'une bibliothèque d'après son seul nom.
2. Séparez les faits des déductions. Les auteurs ont rarement écrit pourquoi ils ont choisi un outil. Marquez chaque décision par "confidence": "evident" (un commentaire, README, ADR ou commit le dit) ou "inferred" (votre meilleure lecture du code). Formulez les raisons inférées comme « probablement parce que… ».
3. Les alternatives doivent être honnêtes. Donnez de véritables compromis dans les deux sens, et dites quand l'alternative serait en fait le meilleur choix.
4. Ignorez le bruit. Les @types/*, plugins de lint et petits assistants sont regroupés en une ligne, pas des fiches individuelles. Consacrez de la profondeur à ce qui façonne l'architecture.
5. Expliquez comme une réponse d'entretien : court, concret, lié à ce dépôt.

Workflow

Étape 0 — Réutiliser le graphe de structure s'il existe

Vérifiez la présence de .ua/knowledge-graph.json (ou de l'ancien .understand-anything/) dans le dépôt cible. Ce fichier est produit par la commande /understand du plugin Understand-Anything. S'il est présent, utilisez ses nœuds, couches et arêtes comme base pour la section d'architecture au lieu de les redériver. S'il est absent, continuez — le scanner ci-dessous donne suffisamment de structure — et mentionnez une fois à la fin que lancer /understand ajoute un graphe cliquable plus riche.

Étape 1 — Analyse déterministe

node <skill>/scripts/scan.mjs <chemin-dépôt> > <chemin-dépôt>/.repo-why/scan.json

(Créez d'abord .repo-why/.) Le scan rapporte, sans intervention de l'IA :

• les manifestes (fichiers package.json incl. les espaces de travail monorepo, requirements.txt, pyproject.toml), les scripts et les fichiers de configuration (tsconfig, tailwind, next.config…)
• chaque dépendance avec sa catégorie, ses alternatives et ses notes de compromis issues de references/catalog.json, ainsi que les fichiers qui l'importent
• les dépendances déclarées mais jamais importées (unused) — méritent une phrase ; ce sont souvent des outils de build, ou véritablement du poids mort
• les occurrences de concepts : correspondances regex pour les modèles dans references/concepts.json (debounce, useMemo, contexte, récupération de données SSR, mises à jour optimistes…) avec fichier:ligne et un extrait
• les tailles des répertoires de premier niveau, les points d'entrée probables, et le résumé Understand-Anything s'il est présent

Lisez scan.json entièrement avant de passer à la suite.

Étape 2 — Cartographier l'architecture

Lisez les points d'entrée, le routeur (app/, pages/, routes/, src/main.*), et un fichier par dossier majeur. Construisez 5 à 15 nœuds d'architecture regroupés en couches (UI, State, API, Service, Data, Infra, External) et les arêtes entre eux (étiquetées : « fetch », « rend », « écrit », « auth via »…). Privilégiez les couches Understand-Anything lorsque vous les avez.

Étape 3 — Fiches de décision (le cœur du rapport)

Pour chaque dépendance significative (framework, kit UI, style, état, récupération de données, formulaires, validation, auth, ORM/DB, tests, build, et tout ce qui est importé dans de nombreux fichiers ou central pour un flux) :

1. Ouvrez 1 à 3 des fichiers dans usedIn et voyez comment elle est réellement utilisée.
2. Remplissez une fiche : rôle dans ce dépôt, pourquoi (évident/inféré), 2 à 4 alternatives avec un compromis pour chacune, et « passerait à X si… ».
3. L'entrée du catalogue vous donne une longueur d'avance, mais adaptez-la à ce dépôt. Les packages absents du catalogue reçoivent quand même une fiche s'ils sont importants — utilisez vos propres connaissances et dites-le.

Rédigez également une comparaison au niveau de la pile pour le framework lui-même (par exemple Next.js vs Remix vs Vite+React vs Nuxt) — les recruteurs la demandent presque toujours.

Étape 4 — Concepts

Pour chaque concept avec occurrences (et tout concept important que vous remarquez et que les expressions régulières ont manqué), ouvrez l'occurrence, puis expliquez : ce que c'est en 2 à 3 phrases, pourquoi c'est nécessaire à cet endroit précis, et un piège. Exemple : debounce sur un champ de recherche — évite un appel API par frappe ; piège : une fermeture périmée si la fonction debounced est recréée à chaque rendu (enveloppez-la dans useMemo/useCallback).

Étape 5 — Flux

Tracez 1 à 3 parcours utilisateur clés de bout en bout (par exemple « l'utilisateur se connecte », « l'utilisateur recherche des produits », « soumission de formulaire → BD »). Chaque étape nomme le fichier dans lequel elle se produit.

Étape 6 — Questions d'entretien

Rédigez 10 à 20 questions qu'un recruteur poserait sur ce projet, avec des réponses ancrées dans le dépôt : architecture, choix spécifiques, compromis, passage à l'échelle, performances, sécurité, tests, « que changeriez-vous ». Incluez au moins trois questions « pourquoi X et pas Y ».

Étape 7 — Écrire et générer

Écrivez tout dans <dépôt>/.repo-why/report.json en suivant exactement references/report-schema.md, puis :

node <skill>/scripts/render.mjs <dépôt>/.repo-why/report.json     # → report.html
node <skill>/scripts/to-drawio.mjs <dépôt>/.repo-why/report.json  # → architecture.drawio

report.html est une page autonome (graphe d'ensemble, fiches de décision avec filtre par catégorie, concepts, flux, pratique d'entretien avec réponses masquées). architecture.drawio s'ouvre dans diagrams.net / l'extension VS Code draw.io, avec une page pour l'architecture et une par flux.

Terminez par un bref résumé de chat : la pile en une ligne, les 3 à 5 décisions les plus intéressantes pour un entretien, et les chemins des fichiers générés. Suggérez d'ajouter .repo-why/ au .gitignore si l'utilisateur ne souhaite pas le versionner.

Contrôle du périmètre

• Dépôt volumineux ou monorepo : demandez sur quelle application/package se concentrer, ou traitez d'abord le plus central et listez les autres.
• L'utilisateur pose une question sur un point précis (« pourquoi zustand ici ? ») : sautez le rapport complet ; répondez à cette question avec les mêmes preuves + alternatives + style de réponse d'entretien.