running-an-architectural-assessment

Phase 2 (Recherche) — Playbook approfondi pour un initiative shepherd. Livrables : une Évaluation Architecturale — une page Confluence dans le dossier assessments de l'EN-space qui capture l'énoncé du problème affiné, l'état actuel, 2–4 options de solution évaluées, et une recommandation avec justification. Budget temps : 3–5 semaines, 40–80 heures de temps shepherd. Se divise en Partie A (~semaines 1–2) comprendre le problème, Partie B (~semaines 3–5) trouver la bonne direction.

Partie A : Comprendre le problème (~Semaines 1–2)

Entretiens avec les parties prenantes

Interrogez 3–5 personnes affectées par le problème ou ayant des connaissances à ce sujet. Élargissez la portée quand l'initiative couvre plusieurs équipes ou touche des systèmes opérationnels ; réduisez-la quand c'est une question technique claire.

Qui consulter :

• Responsables techniques des équipes dont les bases de code changeront.
• Ingénieurs qui ont rencontré le problème à plusieurs reprises et en ont des modèles fonctionnels (même s'ils ne sont pas le responsable technique).
• Responsables SRE, BRE, DbOps, AppSec ou QA quand le problème touche leur domaine.
• Quiconque a essayé une approche similaire auparavant — même si elle a échoué. Surtout si elle a échoué.

Questions à poser :

• « Décrivez-moi comment ce problème se manifeste pour votre équipe en pratique. »
• « Quels contournements existent aujourd'hui ? »
• « Quelles tentatives ont été faites avant et pourquoi n'ont-elles pas perduré ? »
• « Si nous ne faisions rien pendant un autre trimestre, qu'est-ce qui changerait ? »
• « Quelles contraintes — techniques, organisationnelles, calendaires — façonneraient une solution ? »

Ce à documenter :

• La perspective de chaque interviewé dans son propre cadre (paraphrasez mais gardez son langage).
• La douleur quantifiée autant que possible. « ~3 bugs par trimestre », « ~4 heures par sprint perdues à cause de cela », « incident du 2026-02-14 retracé à cela ». La douleur vague produit des propositions vagues.
• Les contraintes, notamment les implicites — engagements de sécurité, compatibilité V+/-2, auto-hébergement, parité multi-client.
• Les désaccords entre interviewés. C'est du signal, pas du bruit.

Analyse de l'état actuel

Examinez les implémentations existantes dans la base de code. La portée de l'examen dépend de l'initiative — gestion des erreurs, observabilité, authentification, accès aux données, outils de construction/test. Cherchez :

• Incohérences. Cinq équipes résolvant le même problème de cinq façons. Deux services avec des versions divergentes d'un pattern partagé.
• Contournements. Code qui existe uniquement parce que le pattern désiré n'existe pas. Commentaires référençant des tickets jamais résolus.
• Dette technique. Anciens patterns laissés en place parce que la réécriture ne valait pas le coût — mais le coût de les laisser est maintenant plus grand que la réécriture.
• Impact. Autant que possible, joignez des chiffres : fréquence des bugs dans la zone, métriques de performance, pages on-call liées à la zone, temps passé en relecture de code sur ce type de code.

Contexte historique

• Lisez les PRs passées, docs de design, et fils Slack sur le sujet. Cherchez dans Confluence les évaluations précédentes dans le même espace de problème.
• Trouvez les anciens shepherds, EMs ou ingénieurs qui ont poussé le travail connexe. De brefs entretiens épargne des semaines de redécouverte.
• Identifiez pourquoi les approches précédentes ont ou n'ont pas perduré. Les raisons informent généralement ce qui réussira cette fois.

Partie B : Trouver la bonne direction (~Semaines 3–4)

Recherche de solutions

Recherchez les patterns provenant de l'industrie, des bases de code comparables, et du propre antériorité de Bitwarden. L'objectif à ce stade est la largeur, puis les trade-offs — pas la profondeur dans le favori.

• Identifiez 2–4 approches candidates. Moins de 2 signifie que vous avez sauté la comparaison ; plus de 4 signifie généralement que vous ne les avez pas bien classées.
• Pour chaque approche, documentez les trade-offs explicitement : complexité, coût de migration, performance, posture de sécurité, implications opérationnelles, impact auto-hébergement, compatibilité V+/-2, qui construit le framework, qui l'adopte.
• Associez-vous avec les shepherds actuels ou passés dont les initiatives sont adjacentes. Partager les résultats repère les dépendances et conflits tôt.
• Faites intervenir Skill(architecting-solutions) de bitwarden-tech-lead quand les trade-offs sont à l'intérieur du périmètre d'une seule équipe — cette compétence porte l'heuristique de jugement architecturel au niveau d'une équipe.

Soyez honnête sur le candidat favori mais rédigez l'évaluation comme si l'un des 2–4 pourrait gagner. Si vous ne documentez sérieusement qu'une approche, le leadership et le Architecture Council ne peuvent pas vraiment décider — ils sont juste en train de cautionner la vôtre.

Le document Évaluation Architecturale

Placez-le dans le dossier assessments de l'EN-space (le doc funnel lie l'emplacement canonique). Suivez le template « Architectural Assessments » ; les sections ci-dessous sont celles que la page funnel spécifie.

• Énoncé du problème (affiné par la recherche). La version que vous pouvez écrire maintenant et que vous ne pouviez pas écrire à l'Identification.
• Analyse de l'état actuel. Incohérences, contournements, impact quantifié. Référencez du code spécifique ou des preuves de tickets.
• Options de solutions envisagées (2–4). Pour chacune : une brève description, trade-offs clés, estimation d'effort approximative, risques. N'écrivez pas une proposé complète pour chacune — une comparaison clairvoyante est ce qui est nécessaire.
• Approche recommandée. Choisissez-en une. Le doc funnel est explicite que c'est ce que le leadership décide ; équivoquer ruine l'objectif de l'évaluation.
• Justification. Pourquoi cette option et pas les autres. Reliez-la aux contraintes soulevées dans les entretiens et à l'impact dans l'analyse de l'état actuel.
• Estimation d'effort approximative de haut niveau. Référencez les initiatives passées si utile. La taille T-shirt ou semaines-de-shepherd-plus-semaines-d'équipe suffisent.
• Risques et questions ouvertes. Ce qui pourrait invalider la recommandation. Ce qui a besoin d'une PoC pour être répondu.

Exemples forts du doc funnel :

Problème : « La gestion d'état incohérente dans le web vault, l'extension navigateur et l'application desktop cause des bugs de synchronisation » Solutions évaluées : RxJS observables, Redux Toolkit, Zustand, custom event system Recommandation : Redux Toolkit avec parcours de migration clair Justification : Support TypeScript, dev tools, familiarité d'équipe, parcours d'adoption graduelle Étape suivante : Prouver que cela fonctionne dans le module des paramètres de l'extension navigateur

Mauvais patterns à éviter (également du doc funnel) :

• « On devrait utiliser GraphQL parce que c'est moderne » — aucune analyse de problème, aucune alternative.
• « Des services plus petits résoudraient nos problèmes d'échelle » — aucune analyse d'état actuel, aucune évaluation de trade-off.

Sociabiliser le brouillon

• Partagez le brouillon avec les gens que vous avez interviewés. Ils attraperont la déformation de la réalité de leur équipe plus vite que quiconque d'autre.
• Partagez avec les shepherds adjacents. Les conflits interinitiatives sont les moins chers à surfacer ici.
• Pour les initiatives majeures, présentez une preview optionnelle au Architecture Council avant l'examen Phase 3 PoC formel. L'apport du Council à ce stade est une guidance façonnée, pas une barrière.
• Affinez en fonction de l'apport. Le premier brouillon et la version qui va aux décideurs ne devraient pas être le même document.

Critères de sortie

Le doc funnel spécifie la barrière à la fin de Phase 2 :

• Livrable : Document Évaluation Architecturale complété avec 2–4 options de solutions et une approche recommandée.
• Décideur : Leadership d'engineering avec apport du Architecture Council.
• Décisions possibles : Procéder à la PoC / Poursuivre la Recherche (étendre 1–2 semaines) / En attente (revoir dans un futur trimestre) / Refuser.

Quand vous apportez l'évaluation aux décideurs, vous avez besoin :

• D'une présentation de 5–10 minutes qui peut tenir seule — problème, options, recommandation, justification, risques.
• D'une demande claire. Presque toujours « approbation pour démarrer une PoC validant l'Option X dans la zone Y ».
• D'une reconnaissance honnête des questions ouvertes que la PoC est censée répondre.

Mises à jour à l'Initio BW

Pendant la Recherche, mettez à jour l'Initio BW (voir Idea-Based Initiatives pour l'anatomie canonique) :

• Description : Affinez si la compréhension du problème a changé matériellement. Restez au niveau du résumé — l'Évaluation Architecturale est l'artifact détaillé.
• Liens « Relates to » : C'est quand l'inventaire de liens croît le plus vite. Toute tentative antérieure, le travail d'une équipe adjacente, l'outillage existant — liez-le.
• Commentaires : Utilisez les commentaires pour enregistrer les résultats de recherche significatifs, les points de décision, et le feedback des parties prenantes qui n'appartient pas à l'évaluation mais devrait se trouver sur la timeline de l'initiative.
• Statut ARCH idea : Mettez à jour à « 2️⃣ Research » dans JPD.

Erreurs courantes

• Rédiger l'évaluation pour justifier une réponse prédéterminée. Le leadership peut généralement le remarquer. L'évaluation est censée être l'endroit où le jugement de l'équipe s'affiche, pas où il est caché.
• Sauter la quantification. « Cela cause de la douleur » est plus difficile à agir que « cela a causé ~6 heures-sprint de débogage sur les 3 derniers sprints ». Obtenez les chiffres partout où vous le pouvez.
• Ne pas nommer ce qui a échoué avant. Si une tentative antérieure n'a pas perduré, l'évaluation qui n'engage pas ce passé produira une recommandation qui n'engage pas non plus.
• Traiter l'Architecture Council comme une barrière à passer. Le Council est un apport. Vous possédez la recommandation. Apportez des vraies questions, pas un pitch.
• Sur-investir dans la Recherche. La PoC est où l'approche est validée en vrai code. Si la Recherche s'est étirée au-delà de 5 semaines, demandez-vous si vous évitez la PoC parce que vous soupçonnez qu'elle révélera quelque chose.

Référence

• Software Initiative Funnel §2 — description canonique de la phase, critères d'entrée/sortie, exemples.
• Idea-Based Initiatives — comment mettre à jour l'Initio BW à travers la Recherche.
• Technical Strategy Ideas — la Stakeholder & Engagement Map du TSI upstream informe quels points de friction surfacer dans l'évaluation.
• Connexe : Skill(shepherding-an-initiative) pour le playbook parapluie, Skill(running-a-proof-of-concept) pour ce que la Recherche alimente, Skill(architecting-solutions) (dans bitwarden-tech-lead) pour l'heuristique de jugement architecturel au niveau d'une équipe à appliquer quand les options vivent dans le domaine d'une seule équipe.