nicolas-codemate/express-need

Express Need - From Raw Idea to Tickets

<context> This skill transforms a raw need into structured specifications, breaks it down into atomic implementable tickets, and creates them via /create-ticket.

The product-analyst agent handles the analysis in TWO phases:

1. Scout phase — detects cross-cutting concerns and prepares targeted questions
2. Synthesis phase — produces the final structured document with Architectural Constraints

This skill orchestrates the user-facing flow: receive -> scout -> interview (if needed) -> synthesis -> break down -> validate -> create tickets. </context>

Input

Arguments passed from command: $ARGUMENTS

Step 1: RECEIVE

<instructions> Parse `$ARGUMENTS` for the raw need description.

If $ARGUMENTS is empty or contains only flags:

• Use AskUserQuestion to ask: "Décrivez votre besoin en texte libre. Pas besoin d'être structuré, exprimez simplement ce que vous voulez accomplir."
• Store the response as raw_need

If $ARGUMENTS contains text:

• Store the full text as raw_need

Display to user:

## Besoin reçu

{raw_need}

Lancement du scout produit...

</instructions>

Step 2: SCOUT PASS

<instructions> Launch the `product-analyst` agent in scout mode. The agent will either detect cross-cutting concerns and return a `## Clarification Needed` block, OR (if the need is clear enough) return directly the full synthesis document.

Agent:
  subagent_type: product-analyst
  model: sonnet
  description: "Scout need: {short summary of raw_need}"
  prompt: |
    SCOUT PHASE — no answers provided yet.

    Raw need: {raw_need}

    Your job in this invocation:
    1. Lightweight codebase scan (framework, stack, existing patterns)
    2. Detect cross-cutting concerns triggered by the need
    3. For each concern detected, check the framework via Context7 for native solutions
    4. Produce EITHER:
       - A `## Clarification Needed` block with 1-5 targeted questions (if concerns detected)
       - The full synthesis document (if no concerns, need is clear)

    Discipline: only ask questions that would change an architectural decision.
    Do NOT ask generic product questions (persona, success metric) — those belong
    in Open Questions of the final document.

Store the agent's output as scout_output.

Branch on scout output

Detect whether scout_output is a scout report or a full synthesis document:

• If scout_output contains ## Clarification Needed: proceed to Step 3 (INTERVIEW)
• If scout_output contains ## Functional Requirements (final doc): skip Step 3 and 4, set structured_document = scout_output, proceed to Step 5 (TASK BREAKDOWN)

Display to user (only if clarifications are needed):

## Scout produit terminé

J'ai détecté des points critiques qui méritent d'être tranchés avant de produire le spec final. Quelques questions rapides...

</instructions>

Step 3: INTERVIEW

<instructions> Parse the `## Clarification Needed` section of `scout_output`. It contains 1-5 questions, each with a header (Q1, Q2...), a context, a question text, and a list of options.

For each question, use AskUserQuestion to present it to the user:

AskUserQuestion:
  questions:
    - question: "{question text from scout, prefixed with context}"
      header: "{Q header from scout, max 12 chars}"
      multiSelect: false
      options:
        - label: "{option label from scout}"
          description: "{option description from scout}"
        - label: "{option label from scout}"
          description: "{option description from scout}"
        # ... (all options from scout, plus always add:)
        - label: "Autre (préciser)"
          description: "Réponse libre"

If the user picks "Autre (préciser)", follow up with a free-text AskUserQuestion to capture the custom answer.

Collect all answers into a scout_answers structure:

## Scout Answers
- Q1 ({question title}): {answer}
- Q2 ({question title}): {answer}
- ...

Store this block as scout_answers. </instructions>

Step 4: SYNTHESIS

<instructions> Launch the `product-analyst` agent again, this time in synthesis mode, passing the raw need AND the scout answers.

Agent:
  subagent_type: product-analyst
  model: sonnet
  description: "Synthesize need: {short summary of raw_need}"
  prompt: |
    SYNTHESIS PHASE — scout answers provided below.

    Raw need: {raw_need}

    {scout_answers}

    Your job in this invocation:
    1. Produce the full structured document following the Synthesis Phase output format
    2. Bake the scout answers into Architectural Constraints where applicable
    3. Every architectural constraint must have a rationale tied to a product commitment
    4. Self-review before delivering
    5. Return the final document

    Do NOT return Clarification Needed — you have everything you need.

Store the agent's output as structured_document. </instructions>

Step 5: TASK BREAKDOWN

<instructions> Analyze the `structured_document` and propose a breakdown into atomic tickets.

For each Functional Requirement (FR) or logical group of FRs, create a ticket entry:

## Découpage en tickets

| # | Titre | Type | Périmètre | Dépendances |
|---|-------|------|-----------|-------------|
| 1 | {titre concis} | feature/task/bug | FR1, FR2 | - |
| 2 | {titre concis} | feature/task | FR3 | Ticket 1 |
| 3 | {titre concis} | task | AC1, AC2 (tests) | Ticket 1, 2 |

Breakdown Rules

• Each ticket should be implementable in one /resolve session (1 branch, 1 PR)
• A ticket covers 1 to 3 Functional Requirements max
• Mark dependencies between tickets (which must be done first)
• Separate infrastructure/data changes from feature logic
• Tests can be a standalone ticket or grouped with their feature
• Order tickets by dependency chain (infrastructure -> core logic -> integration -> polish)
• Architectural Constraints propagate to EVERY ticket: each ticket's description must carry the relevant architectural constraints from the parent document so implementers see them at resolve time

For each ticket, prepare:

### Ticket {N}: {titre}

**Type**: feature | task | bug
**Exigences couvertes**: FR1, FR2
**Description**:
{2-3 sentences explaining what this ticket accomplishes,
 extracted from the structured document}

**Critères d'acceptation**:
- {AC relevant to this ticket only}

**Contraintes architecturales** (propagated from parent spec):
- {AC-ARCH-N relevant to this ticket, with rationale}

**Contexte technique**:
- {Relevant technical context from the structured document}

</instructions>

Step 6: USER VALIDATION

<instructions> Display the full structured document followed by the task breakdown.

AskUserQuestion:
  questions:
    - question: "Que souhaitez-vous faire avec cette spécification ?"
      header: "Validation"
      multiSelect: false
      options:
        - label: "Valider et créer les tickets"
          description: "Créer tous les tickets proposés via /create-ticket"
        - label: "Valider sans créer"
          description: "Sauvegarder le document sans créer de tickets"
        - label: "Modifier le découpage"
          description: "Ajuster le nombre ou le périmètre des tickets"
        - label: "Modifier la spécification"
          description: "Revenir sur le document de spécification"
        - label: "Approfondir"
          description: "Relancer l'agent pour creuser un aspect spécifique"

Handle response:

• Valider et créer les tickets: Proceed to Step 7 (save), then Step 8 (create tickets)
• Valider sans créer: Proceed to Step 7 (save only)
• Modifier le découpage: Ask what to change, revise breakdown, loop back to Step 6
• Modifier la spécification: Ask for instructions, revise structured_document, redo Step 5, loop back to Step 6
• Approfondir: Ask what aspect, relaunch product-analyst in synthesis mode with targeted prompt, redo Step 5, loop back to Step 6 </instructions>

Step 7: SAVE

<instructions> Generate a filename from the document title: - Take the `# Title` from the structured document - Convert to kebab-case, ASCII only - Prefix with date: `{YYYY-MM-DD}-`

Save the full document (spec + breakdown) to: .claude-work/needs/{filename}.md

mkdir -p .claude-work/needs

Display to user:

## Document sauvegardé

Fichier : .claude-work/needs/{filename}.md

</instructions>

Step 8: CREATE TICKETS (if requested)

<instructions> For each ticket in the breakdown, invoke `/create-ticket` with the prepared content:

For ticket N:
  /create-ticket --type {type} "{title}"
  with description = ticket description + acceptance criteria + architectural constraints + technical context

Between each ticket creation, display progress:

Ticket {N}/{total} créé : {ticket-id} - {titre}

After all tickets are created, display summary:

## Tickets créés

| # | ID | Titre | Type |
|---|-----|-------|------|
| 1 | {id} | {titre} | {type} |
| 2 | {id} | {titre} | {type} |

Ordre d'implémentation recommandé : {dependency chain}

Lancer `/resolve {first-ticket-id}` pour commencer ?

</instructions>

Language

All user communication in French. Technical content (structured document, file paths, code references) in English.