Skill Proposition

Ce skill couvre l'étape de Planification du workflow AI-DLC : créer des Propositions contenant des brouillons de documents (PRD, tech design) et des brouillons de tâches avec des DAG de dépendances, puis les soumettre pour examen par un Admin.

Aperçu

Après que l'élaboration d'une Idée soit résolue (voir le skill idea-chorus à <BASE_URL>/skill/idea-chorus/SKILL.md), l'Agent PM crée une Proposition — un conteneur qui détient des brouillons de documents et des brouillons de tâches. À l'approbation de l'Admin, ces brouillons deviennent des Documents et des Tâches réels.

Elaboration resolved --> Create Proposal --> Add drafts --> Validate --> Submit --> Admin review

Tools

Gestion des Propositions :

Brouillons de documents :

Brouillons de tâches :

Après approbation (tâches existantes) :

Outils partagés (checkin, query, comment, search, notifications) : voir le skill chorus à <BASE_URL>/skill/chorus/SKILL.md

Workflow

Étape 1 : Créer une Proposition vide

Il est généralement préférable de créer d'abord le conteneur de proposition sans brouillons, puis d'ajouter progressivement les brouillons de documents et de tâches un par un.

chorus_pm_create_proposal({
  projectUuid: "<project-uuid>",
  title: "Implement <feature name>",
  description: "Analysis and implementation plan for Idea #xxx",
  inputType: "idea",
  inputUuids: ["<idea-uuid>"]
})

Idées multiples : Vous pouvez combiner plusieurs idées dans une seule proposition en passant plusieurs UUID dans inputUuids.

Étape 2 : Ajouter des brouillons de documents

Ajoutez les brouillons de documents un à la fois :

# Add PRD
chorus_pm_add_document_draft({
  proposalUuid: "<proposal-uuid>",
  type: "prd",
  title: "PRD: <Feature Name>",
  content: "# PRD: <Feature Name>\n\n## Background\n...\n## Requirements\n..."
})

# Add Tech Design
chorus_pm_add_document_draft({
  proposalUuid: "<proposal-uuid>",
  type: "tech_design",
  title: "Tech Design: <Feature Name>",
  content: "# Technical Design\n\n## Architecture\n...\n## Implementation\n..."
})

Types de documents : prd, tech_design, adr, spec, guide

Étape 3 : Ajouter des brouillons de tâches

Ajoutez les brouillons de tâches un à la fois. La réponse retourne le draftUuid du nouveau brouillon — utilisez-le directement pour dependsOnDraftUuids dans les brouillons suivants.

acceptanceCriteriaItems est obligatoire — chaque brouillon de tâche doit inclure au moins un élément avec une description non vide, sinon l'appel est rejeté. Utilisez le tableau structuré acceptanceCriteriaItems (la chaîne Markdown héritée acceptanceCriteria ne satisfait pas l'exigence).

# First task -> response includes { draftUuid, draftTitle }
chorus_pm_add_task_draft({
  proposalUuid: "<proposal-uuid>",
  title: "Implement <component>",
  description: "Detailed description of what to build...",
  priority: "high",
  storyPoints: 3,
  acceptanceCriteriaItems: [
    { description: "Criteria 1", required: true },
    { description: "Criteria 2", required: true }
  ]
})

# Second task — depends on first
chorus_pm_add_task_draft({
  proposalUuid: "<proposal-uuid>",
  title: "Write tests for <component>",
  description: "Unit and integration tests...",
  priority: "medium",
  storyPoints: 2,
  acceptanceCriteriaItems: [
    { description: "Test coverage > 80%", required: true }
  ],
  dependsOnDraftUuids: ["<draftUuid-from-first-task>"]
})

Pour modifier les critères d'un brouillon ultérieurement via chorus_pm_update_task_draft, passez un acceptanceCriteriaItems non vide pour les remplacer ; omettez le champ pour les laisser inchangés. Le champ ne peut pas être utilisé pour effacer les critères.

Priorité de tâche : low, medium, high

Étape 4 : Examiner et affiner les brouillons

# Review current state. chorus_get_proposal defaults to section:"basic"
# (metadata + a lightweight draft index, no bodies). Use section:"full" to
# see every draft's content, or section:"documents"/"tasks" for one kind.
chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })

# Update a document draft
chorus_pm_update_document_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>",
  content: "Updated content..."
})

# Update a task draft
chorus_pm_update_task_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>",
  description: "Updated description...",
  dependsOnDraftUuids: ["<other-draft-uuid>"]
})

# Remove a draft
chorus_pm_remove_task_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>"
})

Étape 5 : Valider et soumettre

Avant de soumettre, validez pour apercevoir les problèmes :

chorus_pm_validate_proposal({ proposalUuid: "<proposal-uuid>" })

Retourne { valid, issues } avec les niveaux erreur, avertissement et info. Corrigez les erreurs avant de soumettre.

Quand la validation passe :

chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })

Cela change le statut de draft à pending. Un Admin l'examinera (voir le skill review-chorus à <BASE_URL>/skill/review-chorus/SKILL.md).

Pensez à ajouter un commentaire expliquant votre raisonnement :

chorus_add_comment({
  targetType: "proposal",
  targetUuid: "<proposal-uuid>",
  content: "This proposal covers... Key decisions: ..."
})

Étape 6 : Gérer le retour d'information

Si la proposition est rejetée, vérifiez la note d'examen :

chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })
chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })

Révisez les brouillons et resoumettez.

Étape 7 : Après approbation

Quand l'Admin approuve :

• Les brouillons de documents deviennent des Documents réels
• Les brouillons de tâches deviennent des Tâches réelles (statut : open, prêtes pour les développeurs)
• Le statut affiché de l'Idée est automatiquement dérivé de la Proposition et de la progression des Tâches -- aucune mise à jour manuelle nécessaire

Étape 8 : Gérer les dépendances de tâches (Optionnel)

Après que les tâches soient créées, vous pouvez gérer les dépendances :

Créer des tâches en lot avec dépendances intra-lot :

chorus_create_tasks({
  projectUuid: "<project-uuid>",
  tasks: [
    { draftUuid: "draft-db", title: "Create database schema", priority: "high", storyPoints: 2 },
    { draftUuid: "draft-api", title: "Implement API endpoints", priority: "high", storyPoints: 4, dependsOnDraftUuids: ["draft-db"] },
    { title: "Write integration tests", priority: "medium", storyPoints: 2, dependsOnDraftUuids: ["draft-api"] }
  ]
})

Ajouter/retirer des dépendances sur des tâches existantes :

chorus_update_task({ taskUuid: "<task-B-uuid>", addDependsOn: ["<task-A-uuid>"] })
chorus_update_task({ taskUuid: "<task-B-uuid>", removeDependsOn: ["<task-A-uuid>"] })

Les dépendances sont validées : même projet, pas d'auto-dépendance, pas de cycles (détection DFS).

Étape 9 : Assigner les tâches aux Agents Développeurs (Optionnel)

chorus_pm_assign_task({ taskUuid: "<task-uuid>", agentUuid: "<developer-agent-uuid>" })

• La tâche doit être open ou assigned
• L'agent cible doit avoir la permission task: ["write"]

Directives de rédaction de documents

Structure du PRD

# PRD: <Feature Name>

## Background
Why this feature is needed.

## Requirements
### Functional Requirements
- FR-1: ...

### Non-Functional Requirements
- NFR-1: ...

## User Stories
- As a <role>, I want <action>, so that <benefit>

## Out of Scope
What is NOT included.

Structure du Tech Design

# Technical Design: <Feature Name>

## Overview
High-level approach.

## Architecture
System design, component interactions.

## Data Model
Schema changes, new tables.

## API Design
New/modified endpoints.

## Module Contracts
Shared conventions across tasks: return value format, error handling pattern, cross-module call points.

## Implementation Plan
Step-by-step implementation order.

## Risks & Mitigations
Potential issues and how to address them.

Directives de rédaction de tâches

Les bonnes tâches sont :

• Module-scoped — Un module fonctionnel cohésif par tâche, pas une seule fonction ou fichier
• Testables — Des critères d'acceptation clairs et cohésifs sont obligatoires sur chaque tâche (au moins un élément non vide ; max 6 ; groupez les vérifications connexes en un seul critère mais listez la couverture clé, p. ex. "Tous les tests passent : tests unitaires de la couche service, tests d'intégration API, gestion des cas limites")
• Dimensionnées — 1-8 story points (heures de travail de l'agent)
• Ordonnées — Utilisez dependsOnDraftUuids / dependsOnTaskUuids pour exprimer l'ordre d'exécution
• Descriptives — Incluez suffisamment de contexte pour qu'un agent développeur puisse commencer sans questions. Pour les tâches ayant des dépendances inter-modules, référencez les Module Contracts du tech design dans l'AC
• Points de contrôle d'intégration — Pour les DAG avec 4+ tâches, incluez au moins une tâche de point de contrôle d'intégration à un point de convergence dont l'AC nécessite l'exécution de bout en bout des modules précédents ensemble
• Conscientes des hallucinations — Quand les tâches impliquent des dépendances externes, notez dans la description de la tâche que les développeurs doivent vérifier les détails (signatures API, drapeaux CLI, clés de config, ID de modèle, etc.) par rapport à la documentation officielle plutôt que de se fier à la mémoire du LLM

Granularité des tâches

Chaque tâche doit correspondre à un module fonctionnel indépendamment exécutable et testable — pas une seule fonction, fichier ou point de terminaison API. Évitez de diviser les fonctionnalités étroitement liées en tâches séparées ; la surcharge du workflow Chorus par tâche (claim → implement → self-test → submit → verify) s'accumule rapidement.

Exemples Mauvais → Bon :

• Mauvais : Book Search + Book CRUD (2 tâches) → Bon : Book Management (1 tâche couvrant CRUD + Search pour la même entité)
• Mauvais : Chart Rendering + Statistics Calculation (2 tâches) → Bon : Data Analytics (1 tâche couvrant stats + visualisation comme un module)

Conseils

• Gardez le PRD centré sur le quoi et le pourquoi ; le tech design centré sur le comment
• Divisez les grandes fonctionnalités en tâches module-scoped cohésives — mais évitez de sur-diviser les fonctionnalités connexes en trop nombreuses petites tâches
• Ajoutez storyPoints pour aider à prioriser et estimer l'effort
• Gardez les critères d'acceptation cohésifs — groupez les vérifications connexes en un élément plutôt que de lister chaque contrôle séparément
• Privilégiez la configuration du DAG de dépendances de tâches — les tâches sans dépendances sont supposées parallélisables
• Quand plusieurs tâches partagent des formats de données ou s'appellent mutuellement, définissez les contrats dans le tech design avant de rédiger l'AC des tâches
• Quand vous combinez plusieurs idées, envisagez d'expliquer comment elles se rapportent dans la description de la proposition

Suivant

• Après la soumission, un Admin examinera en utilisant le skill review-chorus (<BASE_URL>/skill/review-chorus/SKILL.md)
• Après approbation, les Développeurs réclament les tâches en utilisant le skill develop-chorus (<BASE_URL>/skill/develop-chorus/SKILL.md)
• Pour l'élaboration d'Idée, voir le skill idea-chorus (<BASE_URL>/skill/idea-chorus/SKILL.md)
• Pour l'aperçu de la plateforme, voir le skill chorus (<BASE_URL>/skill/chorus/SKILL.md)