design-session

Session de Design

Réfléchissez à un design avec le propriétaire avant que quoi que ce soit ne soit enregistré. Le propriétaire dirige ; l'agent élargit les options, montre ce que chacune implique et maintient la conversation honnête. Rien n'atteint le design système avant l'étape de promotion à la fin, où le propriétaire choisit ce qui entre.

Utilisez-le à tout moment : avant que le design système n'existe, pendant la planification d'un jalon, ou au milieu d'un jalon. Les termes (design système, vérification additive, surfaces de revue, settled/working, owner/proposed, jalon, spike, code provisoire, préférence du propriétaire, règle des deux dérogations) sont définis dans le fichier terms.md de la compétence system-design ; utilisez-les tels qu'ils y sont définis.

Fichiers

<DocDir>/SystemDesign/
  Overview.md                       le design système (system-design) ; modifié seulement par l'étape de promotion
  Sessions/<date>-<Short_Topic>.md  les notes scratch de cette compétence, supprimées après l'étape de promotion

<date> est YYYY-MM-DD ; Short_Topic est 2–3 mots en Snake_Case, par ex. 2026-11-01-Review_Import.md. Les notes sont libres : pas d'IDs, pas de statuts, pas de marques d'accord et pas de limite de questions. Elles contiennent l'esquisse du propriétaire, les formes considérées avec leurs diagrammes, les conséquences tracées, les contradictions trouvées et comment elles ont été résolues, les résultats des spikes, et où le propriétaire penche. Mettez-les à jour à chaque mouvement de la conversation, afin qu'une session qui s'arrête tôt puisse reprendre à partir du fichier.

Flux de travail

1. Lire, puis laisser le propriétaire diriger

Lisez le design système et tout document de sous-système que le sujet touche, le jalon actuel de la feuille de route, <DocDir>/Taxonomy.md, le fichier de règles du projet (CLAUDE.md ou équivalent) et le fichier de préférences du propriétaire ${DANNY_SKILLS_STATE_DIR:-$HOME/.local/state/danny-agent-skills}/owner-preferences.md s'il existe. Si un fichier de notes pour ce sujet existe dans Sessions/, continuez à partir de celui-ci. Sinon, créez-le et indiquez le chemin.

Demandez au propriétaire ce qu'il imagine, et reflétez son esquisse en quelques lignes et, lorsqu'elle comporte deux parties ou plus, un diagramme. Ne demandez que ce qui changerait la forme ; ne demandez jamais ce que vous pourriez énoncer comme une valeur par défaut.

2. Proposer des formes alternatives

Proposez 2 à 3 formes, l'esquisse du propriétaire comptant pour une. Pour chacune : un diagramme Mermaid suivant le fichier diagrams.md de la compétence plan-milestone (les étiquettes des nœuds sont exactement les noms des composants du design système, les nouvelles pièces sont sketched, ce que la forme change est marqué touched), un exemple simple de son comportement sur un cas du projet, et un avantage et un inconvénient en une ligne. Ensuite, recommandez-en une, ou dites « aucune recommandation » et pourquoi. Nommez les nouvelles choses par ce qu'elles font (terms.md, « Noms et étiquettes »). Vérifiez le rendu de chaque diagramme comme le dit diagrams.md.

3. Tracer les conséquences

Pour la forme vers laquelle le propriétaire penche, dites ce qu'elle change : sous-systèmes, coutures, le modèle de données, les surfaces de revue (champ par champ uniquement là), les noms et la section menace et confidentialité. Exécutez la vérification additive par rapport à la ligne de chaque jalon ultérieur : si un jalon ultérieur ne pourrait pas être ajouté sans restructuration, dites quelle couture devrait être décidée maintenant. Sans design système ou sans lignes de jalons ultérieurs encore, sautez la vérification additive jusqu'à ce que des jalons existent ; n'inventez jamais de jalons à vérifier. Nommez chaque élément settled que la forme changerait ; en changer un est un déclencheur de re-planification. Laissez les internes à l'intérieur des coutures indécises ; les menus détails vont sur la liste « décider après exécution ».

4. Détecter les contradictions

Dites-le clairement lorsque quelque chose que le propriétaire dit entre en conflit avec une déclaration antérieure de cette session, un élément settled, une préférence du propriétaire, les règles du projet ou un nom dans Taxonomy.md. Citez les deux côtés et demandez lequel prévaut. Enregistrez la réponse dans les notes.

5. Proposer un spike jetable

Lorsque seul le fait d'exécuter quelque chose résoudra une question (est-ce assez rapide, l'API renvoie-t-elle cela, la plateforme peut-elle faire cela), proposez la plus petite exécution qui y répond : ce qu'elle fait, quel résultat pointe dans quelle direction, et approximativement combien de temps cela prend. Construisez-la uniquement si le propriétaire accepte, en dehors du code produit (un répertoire scratch ou une branche jetable), exécutez-la, et enregistrez le résultat dans les notes. Le code est jeté ; si le propriétaire souhaite le conserver, il est promu en tant que code provisoire à l'étape 6.

6. Promouvoir

Lorsque le propriétaire dit qu'il a terminé, ou que la conversation a convergé, listez chaque élément dans les notes qui pourrait entrer dans le design système, sous la forme du fichier presenting-for-review.md, chacun avec un résultat recommandé :

• Promouvoir comme settled ou promouvoir comme working avec sa note de révision (« revisiter si … »).
• Mettre de côté (Park) pour un jalon ultérieur, en nommant le jalon.
• Abandonner (Drop).

Dans le même message, proposez des lignes de préférence du propriétaire selon la règle des deux dérogations : uniquement là où le propriétaire a dérogé au même type de forme que vous avez proposé deux fois dans cette session, ou a exprimé un goût catégorique. Une ligne chacune (la préférence, un exemple, la date), en indiquant si elle va dans le fichier de préférences inter-projets ou dans le fichier de règles du projet. Une décision unique est une décision, pas une préférence ; les retours sur le comportement de cette compétence vont dans la rétrospective, pas ici. Pour chaque élément dans les termes du propriétaire (un nom, un texte de résultat, une couture), faites une offre de resserrement de l'étape 4 de la compétence system-design une fois dans le même message : listez chaque ambiguïté et montrez une version resserrée à côté de l'originale ; le propriétaire accepte, édite ou conserve. Terminez par une question.

Appliquez les décisions du propriétaire au design système (overview-template.md) sous forme d'une édition normale :

Élément promu	Où il va
Un composant	une ligne Composants (sketched, Cible de construction, Accord) et un nœud de diagramme avec sa classe de profondeur uniquement, jamais touched
Une couture	une ligne Coutures et interfaces avec son Accord
Un tableau, API ou symbole public	Surfaces de revue, champ par champ, avec sa marque
Une entité ou relation	Modèle de données
Un nom	Noms, puis <DocDir>/Taxonomy.md, revus avec le reste comme un ensemble
Un choix entre formes	une ligne Décisions : prochain ID D libre, Type choice, Accord settled ou working (revisit if …), Pourquoi nommant la forme rejetée
Une inconnue découverte par la session	une ligne Risques avec son expérience la moins chère
Un changement à un jalon ultérieur	sa ligne Scope and milestones et la cellule Additive check
Un code spike conservé par le propriétaire	une ligne Code provisoire, et le marqueur PROVISIONAL dans le code
Un élément structurel mis de côté	une ligne Questions ouvertes nommant le jalon qu'il attend, par ex. « Q4 (mis de côté jusqu'à M3, enregistrer les modifications) : … »
Un menu détail mis de côté	la liste « décider après exécution », sous le jalon qui le tranchera

Les marques d'accord suivent le modèle : un élément que le propriétaire a écrit ou édité est owner (par ex. settled · owner) ; un élément que le propriétaire a accepté inchangé ne porte pas de marque proposed. Les nouveaux IDs continuent la séquence du document et ne sont jamais réutilisés. Un changement à un élément convenu passe par le journal des décisions, pas par une modification silencieuse. Lorsqu'un élément promu modifie un élément settled (une couture, par exemple) ou qu'une demande du propriétaire ajoute de la structure au jalon actuel, dites clairement qu'une re-planification est nécessaire, et après les validations ci-dessous, écrivez une note de passation pour que /rung achemine la re-planification dans toute session ultérieure : <DocDir>/Handoff/replan-<date>.md avec Route: replan, Model: opus, Waiting on: re-plan after the design session on <topic>, Date:, et un corps nommant les éléments modifiés et la validation (handoff.md). Les éléments abandonnés ne sont pas enregistrés ; le fichier de notes dans l'historique git les conserve. Écrivez les lignes de préférence acceptées dans le fichier que le propriétaire a choisi.

Si aucun design système n'existe encore, écrivez les éléments promus dans un nouveau Overview.md avec l'en-tête du modèle (Status: draft) et seulement les sections qu'ils remplissent ; system-design continue à partir de là.

Validez (commit), en organisant par chemin explicite, le design système, Taxonomy.md, le fichier de règles du projet s'il a changé, et le fichier de notes, avec le message Design session: <topic>, afin que l'historique conserve les notes. Ensuite, git rm le fichier de notes et validez cela avec le message Remove design session notes: <topic>. Enregistrez un événement step avec skill design-session 1.0.1 et kind design-session (autres champs dans le journal métrique de tasklist-run), plus les comptes des éléments que vous avez proposés pour la promotion : proposed, accepted (inchangé), edited et rejected.

Terminez par une phrase simple indiquant ce qui a changé et quelle est la prochaine étape, puis Next: /rung, en ajoutant (Opus: /model opus) lorsque cette étape nécessite Opus : un design système encore à convenir, une planification de jalon, ou une re-planification que l'étape 6 a dit être nécessaire.

Si le propriétaire s'arrête avant la promotion, laissez le fichier de notes en place, non validé, et dites son chemin ; la prochaine session de design sur le sujet continuera à partir de celui-ci.

Si un fichier ou une compétence lié est manquant

Lorsqu'un fichier lié est absent, ne vous arrêtez pas : utilisez le minimum ici, et dites une fois, en une ou deux lignes, ce qui manque et comment l'installer (claude plugin install project-planning@danny-sung-agent-skills, ou npx skills add dannys42/agent-skills --skill <skill-name> dans le même répertoire de compétences pour que les liens relatifs fonctionnent).

• Pas de terms.md : settled est censé tenir ; working est suffisant pour commencer et nomme ce qui nous ferait le revisiter ; les éléments owner sont les mots du propriétaire, proposed ceux de l'agent. La vérification additive demande si chaque jalon ultérieur peut être ajouté sans restructuration.
• Pas de diagrams.md : Mermaid flowchart, citez chaque étiquette, les étiquettes sont les noms des composants, une classe par profondeur (sketched en tirets, designed fin, built gras).
• Pas de presenting-for-review.md : éléments importants en premier (au plus 5, difficiles à inverser ou de large portée), chacun avec des options, un exemple simple, un avantage et un inconvénient et une recommandation ; terminez par une question.
• Pas de overview-template.md : promouvez dans les sections existantes du design système, en faisant correspondre leurs tableaux et marques.

Jugements

• Le propriétaire dirige. Proposez des formes et des conséquences ; n'interrogez pas et n'orientez pas vers votre préférée. Une question qui ne changerait pas la forme ne vaut pas la peine d'être posée.
• Explorez librement, promouvez étroitement. Tout peut être discuté dans la session, mais seule la structure entre dans le design système : sous-systèmes, coutures, modèle de données, surfaces de revue, noms, décisions et risques. Les internes restent en dehors.
• Un spike bat une dispute. Lorsque le propriétaire et l'agent sont en désaccord sur un fait qu'une courte exécution réglerait, proposez l'exécution plutôt que de débattre.