0x0w1/jig

README

Utilisez cette compétence pour créer ou mettre à jour le fichier README.md du dépôt à partir de l'état réel du dépôt.

Procédure

1. Analysez le dépôt :
   • Fichiers de manifeste et de build : pyproject.toml, package.json, Cargo.toml, go.mod, Makefile, fichiers de verrouillage.
   • Points d'entrée, définitions d'arguments CLI, scripts et configurations de service (Dockerfile, docker-compose*.yml).
   • Documentation existante sous docs/ et exemples d'utilisation dans le code.
2. Classez le type de projet : outil CLI, bibliothèque, service/application, ou autre. Le type sélectionne la disposition des sections ci-dessous lorsqu'aucun profil n'est défini.
3. Établissez le profil README conformément au contrat de profil ci-dessous. Un profil qui se résout remplace les valeurs par défaut génériques pour ce dépôt ; lorsqu'aucun ne se résout, proposez-en un et continuez de toute façon.
4. Embranchez selon l'état actuel :
   • Pas de README.md → chemin de création : rédigez le README avec la disposition des sections ci-dessous.
   • README.md existe → chemin de mise à jour : vérifiez chaque affirmation vérifiable du README — commandes, options, chemins de fichiers, liens, déclarations de fonctionnalités — par rapport au dépôt. Collectez les divergences dans une liste d'écarts, signalez la liste, puis appliquez les corrections. Laissez les sections toujours exactes intactes.
5. Appliquez les règles de précision à chaque ligne écrite.
6. Exécutez la passe de compression à partir des règles de compression ci-dessous :
   • Chemin de création : appliquez-la lors de la rédaction. Rien n'a encore été publié, donc il n'y a rien à proposer.
   • Chemin de mise à jour : collectez les duplications et les exagérations dans une proposition — nommez chaque fait, où il est répété, et quel document détaillé le contiendrait — puis demandez avant de déplacer quoi que ce soit. Signalez la proposition même si l'utilisateur la refuse.
7. Fusionnez le changement :
   • Lorsque le dépôt possède la compétence develop-task-flow (ou la jig-develop-task-flow installée), suivez-la : une branche chore/<slug>, une fusion squash avec un commit docs:, puis poussez develop.
   • Sinon, proposez un commit normal sur la branche actuelle.

Contrat de profil

Deux dépôts du même type de projet écrivent encore leurs README différemment : l'un conserve un miroir traduit, un autre déplace l'installation dans un guide, un troisième a une convention de tableau que ses contributeurs suivent déjà. Ce sont des décisions, pas des faits que le dépôt peut analyser, donc elles sont enregistrées une fois et lues à chaque exécution ultérieure.

Résolvez le profil dans cet ordre :

1. Variable d'environnement JIG_README_PROFILE.
2. git config --local --get jig.readmeProfile.
3. .jig/readme.md.

Lorsqu'un profil se résout, il remplace la disposition des sections et les règles de langue ci-dessous pour ce dépôt ; tout ce qu'il ne mentionne pas revient à celles-ci. Lisez-le, suivez-le et nommez-le dans le rapport.

Lorsqu'aucun ne se résout, rédigez-en un à partir de l'analyse et proposez-le : le type classifié, la langue dans laquelle le dépôt écrit déjà, si un miroir existe, l'ordre des sections que le README actuel implique, et quels documents détaillés contiennent déjà le trop-plein. Écrivez .jig/readme.md uniquement après que l'utilisateur l'a accepté. Si l'utilisateur refuse ou ne répond pas, continuez avec les valeurs par défaut génériques et dites-le — un profil manquant est un état normal, pas un blocage.

Le fichier n'enregistre que des décisions. Il ne comporte ni seuils ni liste de contrôle ; la qualité du README reste un jugement que cette compétence porte avec le dépôt sous les yeux.

# Profil README

> Base : <comment cela a été décidé>, <AAAA-MM-JJ>

## Langues

Canonique : `README.md` (anglais). Miroir : `README.ko.md` (coréen), mis à jour dans la même tâche.

## Sections

Titre et ligne de liens, Ce que c'est, Démarrage rapide, Compétences, Documentation, Licence.

## Documents détaillés

Options d'installation → `docs/installation.md`. Feuille de route et enregistrements de conception → `docs/roadmap.md`, liés depuis l'accueil de la documentation uniquement.

## Conventions

Les tableaux d'identifiants gardent les cellules de description à une proposition. Les commandes des contributeurs restent dans un bloc `<details>`.

Les titres de section sont le contrat ; le texte sous eux est celui du dépôt. Un profil écrit avant l'existence de ces titres se lit toujours correctement s'il les utilise.

Disposition des sections

Sections requises, dans l'ordre :

1. Titre plus une description d'une ligne.
2. Introduction : ce que fait le projet et pourquoi il existe.
3. Installation.
4. Utilisation.

Ajouts par type de projet :

• Outil CLI : un tableau de commandes et d'options.
• Bibliothèque : un résumé de l'API avec un exemple de code.
• Service/application : comment l'exécuter (dev et prod) et les variables d'environnement requises.

Facultatif : liens vers la documentation, licence.

Règles de disposition

• Un tableau convient pour les identifiants que les gens copient — noms de compétences, commandes, options, chemins. Ce qui casse un tel nom, c'est le rapport de largeur entre les colonnes : GitHub dimensionne les colonnes par le contenu, donc une colonne de description plusieurs fois plus longue que la colonne d'identifiant comprime l'identifiant jusqu'à ce qu'il soit coupé au milieu du nom, et le lecteur voit un nom qui n'existe pas.
• Gardez les cellules de description à peu près aussi courtes que les identifiants, environ une proposition. Lorsque les descriptions sont longues, soit coupez-les, soit déplacez le tout vers une liste : - **\nom`** — description`.
• Le retour à la ligne à l'intérieur d'une description est attendu et ne nécessite aucun travail.

Règles de compression

Un README est lu avant que le lecteur ait décidé d'utiliser le projet. Tout ce qu'il contient entre en concurrence pour cette attention, donc la longueur est un symptôme : un long README est presque toujours un fait écrit à plusieurs endroits, pas un projet qui a beaucoup à dire.

Déplacez, ne supprimez pas. Lorsque le même fait apparaît à plus d'un endroit, conservez-le à l'endroit où un lecteur arrive en premier et déplacez le reste dans le document détaillé qui le couvre déjà, en créant ce document seulement si aucun n'existe. Rien n'est perdu ; le README cesse de se répéter. Il n'y a pas de nombre de lignes à atteindre — un README de bibliothèque avec les exemples d'API dont elle a vraiment besoin n'est pas trop long, et un README court qui dit la même chose deux fois est toujours faux.

Commencez par ce que le lecteur obtient. L'introduction dit ce qui devient plus facile, pas quelles fonctionnalités existent. « enregistre une bande-annonce de version classée lors de la fusion » est une fonctionnalité ; « vous cessez de reconstruire pourquoi une version était mineure » est ce que le lecteur obtient. Ordonnez les affirmations par la force de leurs preuves, la plus forte en premier, et faites en sorte que tout texte environnant les liste dans le même ordre — un paragraphe et ses puces ne doivent pas impliquer des priorités différentes.

Affirmez uniquement ce que le dépôt peut prouver, et dites quand cela s'applique. Une affirmation que le dépôt ne peut pas démontrer est omise, pas atténuée. Énoncez la condition sous laquelle la valeur apparaît, afin qu'un lecteur en dehors de cette condition puisse écarter rapidement le projet plutôt que de le découvrir plus tard.

Coupez ce qui n'est pas lu avant l'installation. Les feuilles de route, les enregistrements de conception et les notes d'orientation sont des choses que le projet conserve pour lui-même. Liez-les depuis l'accueil de la documentation, pas depuis le README.

Pliez le matériel pour contributeurs. Les commandes de construction, de régénération et de validation servent les personnes qui ont déjà cloné le dépôt. Mettez-les dans un bloc <details> ou un document pour contributeurs.

Fusionnez les blocs qui diffèrent par une seule valeur. Des blocs de commandes séparés par plateforme ou cible qui ne varient que par un argument deviennent un seul bloc avec cet argument nommé.

Donnez au lecteur un moyen de passer le haut. Lorsque le README a plus d'environ quatre sections, mettez une ligne de liens d'une ligne sous le titre afin qu'un lecteur qui revient saute directement à la section qu'il est venu chercher.

Règles de précision

• N'écrivez que des commandes d'installation et d'exécution vérifiées par rapport au dépôt : un script, un manifeste ou un fichier de verrouillage doit les montrer.
• Vérifiez que chaque chemin de fichier lié existe.
• Ne décrivez pas de fonctionnalités, de badges ou d'intégrations que le dépôt ne contient pas.
• Lorsqu'une affirmation ne peut pas être vérifiée, laissez-la de côté et signalez-la à la place.

Règles de sécurité

• .jig/readme.md n'est écrit qu'après que l'utilisateur a accepté la proposition, et jamais comme effet secondaire d'une mise à jour ordinaire du README.
• Un .jig/readme.md existant n'est jamais écrasé sans confirmation explicite. Proposez le changement et nommez ce qu'il remplace.
• Rien d'autre sous .jig/ n'est touché. version-rubric possède .jig/versioning.md.
• Un README publié n'est jamais restructuré silencieusement ; la passe de compression propose et attend.
• Les modifications non liées de l'utilisateur sont préservées.

Règles de langue

• Un README existant conserve sa langue.
• Un nouveau README est rédigé dans la langue que le dépôt utilise déjà pour ses documents, par défaut en anglais, avec les termes techniques entre backticks.
• Une demande explicite de langue de l'utilisateur remplace les deux.

Rapport

• Type de projet et chemin emprunté (création ou mise à jour).
• Profil README : chemin et source, ou proposé et refusé, ou aucun et exécution avec les valeurs par défaut génériques.
• Sur le chemin de mise à jour : la liste des écarts et ce qui a été corrigé.
• La proposition de compression : chaque fait répété à plus d'un endroit, où il serait déplacé, et si l'utilisateur l'a acceptée.
• Les affirmations qui n'ont pas pu être vérifiées et ont été laissées de côté.