Plan d'affinage Humanize

Affine un plan annoté contenant des blocs CMT: / ENDCMT en un plan sans commentaires plus un registre QA, tout en préservant la structure gen-plan et l'état de convergence.

L'installateur hydrate cette compétence avec un chemin de runtime absolu :

{{HUMANIZE_RUNTIME_ROOT}}

flowchart TD
    BEGIN([BEGIN]) --> SETUP[Parse arguments and derive paths<br/>Resolve mode, output path, QA path, alt-language]
    SETUP --> LOAD_CFG[Load merged config<br/>Reuse humanize config precedence and defaults]
    LOAD_CFG --> VALIDATE[Validate IO<br/>Run: {{HUMANIZE_RUNTIME_ROOT}}/scripts/validate-refine-plan-io.sh --input &lt;annotated-plan&gt; [--output ...] [--qa-dir ...] [--discussion|--direct]]
    VALIDATE --> VALID_OK{Validation passed?}
    VALID_OK -->|No| REPORT_VALIDATION[Report validation error<br/>Stop]
    REPORT_VALIDATION --> END_FAIL([END])
    VALID_OK --> EXTRACT[Read input plan and extract valid<br/>CMT:/ENDCMT blocks with a stateful scanner]
    EXTRACT --> PARSE_OK{Parse succeeded?}
    PARSE_OK -->|No| REPORT_PARSE[Report parse error with<br/>line, column, heading, context<br/>Stop]
    REPORT_PARSE --> END_FAIL
    PARSE_OK --> CLASSIFY[Classify comments:<br/>question, change_request, research_request]
    CLASSIFY --> AMBIG{Ambiguous comments?}
    AMBIG -->|Yes, discussion mode| ASK_USER[Ask the minimum user question<br/>needed to continue]
    ASK_USER --> PROCESS
    AMBIG -->|No| PROCESS[Process comments in order:<br/>answer, refine plan, or do targeted repo research]
    PROCESS --> REFINE[Generate refined plan text<br/>Keep required gen-plan sections intact]
    REFINE --> PLAN_CHECK{Plan still valid?<br/>No CMT markers, references consistent,<br/>routing tags valid}
    PLAN_CHECK -->|No, fixable| FIX[Repair internal inconsistencies]
    FIX --> PLAN_CHECK
    PLAN_CHECK -->|No, blocking| REPORT_BLOCK[Report blocking inconsistency<br/>Stop]
    REPORT_BLOCK --> END_FAIL
    PLAN_CHECK -->|Yes| QA[Populate QA document from<br/>{{HUMANIZE_RUNTIME_ROOT}}/prompt-template/plan/refine-plan-qa-template.md]
    QA --> ALT_LANG{Generate translated variants?}
    ALT_LANG -->|Yes| VARIANTS[Translate refined plan and QA<br/>Keep identifiers unchanged]
    ALT_LANG -->|No| ATOMIC
    VARIANTS --> ATOMIC[Write refined plan, QA, and variants<br/>atomically via temp files]
    ATOMIC --> REPORT_SUCCESS[Report success:<br/>paths, counts, mode, convergence status]
    REPORT_SUCCESS --> END_SUCCESS([END])

Exigences d'entrée

Arguments obligatoires :

• --input <path/to/annotated-plan.md> - Plan d'entrée qui suit déjà le schéma gen-plan et contient au moins un bloc CMT: / ENDCMT

Arguments optionnels :

• --output <path/to/refined-plan.md> - Chemin de sortie pour le plan affiné ; par défaut en mode in-place (--input)
• --qa-dir <path/to/qa-dir> - Répertoire pour le registre QA généré ; par défaut .humanize/plan_qa
• --alt-language <language-or-code> - Langue de sortie traduite optionnelle pour les variantes du plan et de la QA
• --discussion - Demander à l'utilisateur de résoudre les classifications ambiguës ou les décisions linguistiques
• --direct - Résoudre l'ambiguïté avec l'hypothèse la plus petite et sûre et l'enregistrer dans la QA

Règles des arguments :

• --discussion et --direct s'excluent mutuellement
• Le validateur n'accepte pas --alt-language, ne passez donc pas ce drapeau à validate-refine-plan-io.sh
• Si --output est omis, affinez le plan sur place et écrivez quand même le document QA séparément

Garanties du flux de travail

Le flux d'affinage doit :

• Préserver le schéma gen-plan au lieu d'inventer de nouvelles sections de haut niveau
• Supprimer tous les blocs CMT: / ENDCMT résolus du plan final
• Conserver les sections obligatoires intactes :
  • ## Goal Description
  • ## Acceptance Criteria
  • ## Path Boundaries
  • ## Feasibility Hints and Suggestions
  • ## Dependencies and Sequence
  • ## Task Breakdown
  • ## Claude-Codex Deliberation
  • ## Pending User Decisions
  • ## Implementation Notes
• Préserver les sections optionnelles le cas échéant, y compris l'appendice du brouillon de conception original
• Garder les balises de routage des tâches limitées à coding ou analyze
• Générer un registre QA à partir du modèle QA fourni
• Écrire le plan affiné, le fichier QA et les variantes linguistiques de manière atomique

Classification et sortie

Chaque bloc de commentaire brut extrait reçoit une classification dominante :

• question
• change_request
• research_request

Le flux produit :

• Un plan affiné avec les blocs de commentaires supprimés et les affinements approuvés appliqués
• Un registre QA qui enregistre :
  • une ligne par CMT-N brut
  • classification et disposition
  • réponses aux questions
  • résultats de recherche
  • modifications du plan appliquées
  • décisions en attente
  • métadonnées d'affinage et état de convergence

Langues alternatives prises en charge

--alt-language prend en charge ces valeurs normalisées :

Règles :

• Accepter soit le nom de langue soit le code ISO
• Traiter English / en comme un no-op
• Garder les identifiants inchangés dans les variantes traduites
• Si la langue alternative correspond à la langue du plan principal, ignorer la génération de variante

Codes de sortie de validation

Utilisation

# Démarrer le flux
/flow:humanize-refine-plan

# Le flux demandera :
# - Chemin du plan annoté d'entrée
# - Chemin optionnel du plan affiné de sortie
# - Répertoire QA optionnel
# - Mode d'exécution optionnel et langue alternative

Ou avec la compétence seulement (sans exécution automatique) :

/skill:humanize-refine-plan