m1nga/map-product-system

Cartographier le système produit

Construire un modèle partagé de la façon dont le produit fonctionne, de l'intention utilisateur au résultat système. Accepter des explications brutes, dictées, désordonnées ou multilingues directement ; ne pas exiger de prompt optimisé au préalable. Répondre dans la langue de l'utilisateur.

Principes de fonctionnement

• Préserver l'intention produit avant d'ajouter de la structure.
• Distinguer Connu, Inféré, Proposé et Inconnu. Ne jamais présenter une invention comme un fait existant.
• Ne pas remplir les affirmations Connues à partir de la mémoire du modèle. Un fait rappelé à partir des données d'entraînement plutôt qu'observé dans les sources de l'utilisateur est au mieux Inféré.
• Rechercher la traçabilité, pas une longue liste de souhaits de fonctionnalités. Un système est bien cartographié lorsque les parcours, les capacités, les décisions, les données, les acteurs, les états et la gestion des pannes sont connectés de bout en bout.
• Séparer les fondations à l'échelle du produit du comportement spécifique au locataire.
• Faire des recommandations de conception conséquentes. Expliquer brièvement le compromis au lieu de se cacher derrière une liste d'options non classées.
• Adapter la profondeur à la demande. Ne pas imposer un rapport d'architecture complet pour une question étroite.
• Effectuer des vérifications de couverture larges en interne ; n'exposer que la structure, les lacunes et les preuves qui affectent la décision de l'utilisateur, sauf si un artefact exhaustif est demandé.

Choisir le travail

1. Découvrir — transformer une idée précoce ou incomplète en premier modèle système cohérent.
2. Auditer — inspecter le code existant, les documents, les diagrammes ou le comportement et identifier les lacunes, contradictions et architecture accidentelle.
3. Évoluer — placer une nouvelle fonctionnalité ou mandat dans le modèle existant et tracer ses effets en aval.

Lorsque des sources existent, les inspecter avant de proposer une structure. Traiter le comportement du dépôt et les documents actuels comme des preuves, pas automatiquement comme l'intention produit correcte.

Construire le modèle

1. Établir la colonne vertébrale du produit

Identifier le résultat produit, les acteurs, les jobs à réaliser, les points d'entrée, les états finaux réussis, la limite métier et les non-objectifs importants. Inférer les lacunes non bloquantes et les étiqueter. Ne demander que lorsque des réponses différentes changeraient matériellement la fondation.

2. Cartographier de l'extérieur vers l'intérieur

Tracer chaque acteur important à travers la découverte, l'intégration, la configuration, l'utilisation normale, la révision ou approbation, la gestion des exceptions et l'exploitation continue. Dériver les capacités de ces parcours au lieu de commencer par les composants internes.

Pour chaque capacité importante, tracer :

déclencheur → entrées → décision/règle → action → sortie → changement d'état → consommateur en aval → échec/récupération → observabilité

3. Cartographier de l'intérieur vers l'extérieur

Connecter les capacités aux surfaces produit, logique métier, résolution des mandats/règles, orchestration, agents et services, intégrations, magasins de données, analyses, sécurité et opérations. Rendre la propriété et les limites explicites.

Pour le travail à l'échelle du produit, mandat, données, multi-agents ou exhaustivité, lire references/coverage-model.md et n'utiliser que les lentilles pertinentes.

4. Résoudre code, mandat, configuration et données

Lorsque le produit prend des décisions régies ou spécifiques au client, classer le comportement délibérément :

• Code — mécanismes stables, invariants, validation, application et primitives d'exécution.
• Mandat plateforme — autorité à l'échelle du produit versionnée, interdictions, règles de sécurité et gouvernance appliquée à chaque client.
• Mandat client — objectifs client versionnés, règles métier, permissions, préférences, seuils et chemins d'escalade, contraints par le mandat plateforme.
• Mandat runtime — la politique résolue et vérifiable pour une exécution, incluant identités, versions, périmètre des données, outils, approbations et limites.
• Configuration — choix opérationnels pouvant changer sans redéfinir l'autorité ou le sens du produit.
• Données — faits et événements observés ; ne jamais utiliser de données mutables comme source de politique implicite sans règle de résolution explicite.

Préférer un pipeline de résolution plutôt que des conditionnelles client dispersées :

mandat plateforme + mandat client + contexte runtime → valider/résoudre → mandat runtime → exécution + enregistrement d'audit

Pour les produits sans décisions régies ou spécifiques au client, séparer code, configuration et données est suffisant ; ne pas forcer les couches de mandat sur un produit qui n'en a pas.

5. Concevoir la responsabilité, pas une collection d'agents

N'introduire un agent que lorsque le contexte, les outils, l'autorité, l'évaluation, la mise à l'échelle ou l'isolation des pannes indépendants le justifient. Sinon, utiliser du code déterministe, un service, une étape de workflow ou une décision humaine.

Donner à chaque agent/service/rôle humain un contrat : but, déclencheur, entrées, données et outils autorisés, autorité de décision, sorties, état, transferts, comportement de timeout/défaillance, évaluation et propriétaire. Signaler les transferts circulaires, l'autorité dupliquée, l'état partagé caché et les résultats sans propriétaire.

6. Défier l'exhaustivité

Exécuter les passes de couverture pertinentes depuis la référence. Au minimum :

• Tracer chaque parcours principal vers les capacités et les propriétaires système.
• Tracer chaque décision importante vers l'autorité du mandat, les preuves et la vérifiabilité.
• Tracer les données capturées vers le consentement, la lignée, la rétention, les consommateurs, l'analyse et la suppression.
• Tracer les chemins heureux, les défaillances récupérables, les défaillances irrécupérables et l'escalade humaine.
• Vérifier l'isolation des locataires, les permissions, l'observabilité, le versioning, le rollback, le coût et la propriété opérationnelle.
• Séparer les exigences de lancement de l'extensibilité ultérieure ; ne pas déguiser la spéculation en scope MVP.

Livrer le résultat

Commencer par le modèle actuel le plus clair et la décision la plus conséquente. Utiliser le plus petit mélange utile de prose, tableaux, diagrammes et listes.

Pour une demande de système complet, fournir normalement :

1. Colonne vertébrale et scope du produit.
2. Carte des parcours et capacités de bout en bout.
3. Couches système et limites clés.
4. Architecture des mandats et des données.
5. Modèle opérationnel agent/service/humain.
6. Exigences transversales critiques et chemins de défaillance.
7. Décisions, hypothèses, inconnues et contradictions.
8. Tranches de livraison séquencées et packages de travail assignables indépendamment.

Chaque package de travail doit nommer son résultat, ses dépendances, le type de propriétaire, les interfaces affectées, les preuves d'acceptation et les décisions encore requises. Ne pas générer d'agents simplement parce que l'architecture les nomme ; déléguer seulement lorsque l'utilisateur demande une exécution ou un travail d'agent.

Lors de la maintenance d'un artefact d'architecture vivant, mettre à jour la source de vérité existante au lieu de produire un document concurrent. Préserver l'historique des décisions et montrer ce qui a changé. Garder l'artefact dans le projet de l'utilisateur, pas à l'intérieur de ce package de compétence ; si aucun fichier ne peut être écrit, sortir l'artefact complet sous forme de texte copiable.

Vérification finale

Avant de terminer, vérifier que le résultat :

1. Répond comment le produit crée de la valeur, pas seulement comment les composants se connectent.
2. Sépare les preuves actuelles des recommandations.
3. Rend chaque parcours critique et chaque décision traçables de bout en bout.
4. Expose des lacunes significatives plutôt que de revendiquer une certitude impossible.
5. Se termine par des décisions ou des travaux exécutables, pas par du théâtre d'architecture.