spec-gather-requirements

name	spec-gather-requirements
description	Spec Pipeline: Gather Requirements methodology and workflow
agent	architect
subtask	false

Spec Pipeline: Gather Requirements

Purpose

Coletar e estruturar requisitos do usuário através de elicitation interativo. Transforma descrições informais em requisitos formais e categorizados.

---

autoClaude

autoClaude:
  version: '3.0'
  pipelinePhase: spec-gather

  elicit: true
  deterministic: false # LLM creativity needed for understanding intent
  composable: true

  inputs:
    - name: storyId
      type: string
      required: true
      description: ID da story sendo especificada

    - name: source
      type: enum
      values: [prd, user, existing]
      required: false
      default: user
      description: Fonte dos requisitos

    - name: prdPath
      type: string
      required: false
      description: Caminho para PRD se source=prd

    - name: existingSpec
      type: string
      required: false
      description: Spec existente se iterando

  outputs:
    - name: requirements.json
      type: file
      path: docs/stories/{storyId}/spec/requirements.json
      schema: requirements-schema

  verification:
    type: schema
    schemaRef: requirements-schema

  contextRequirements:
    projectContext: true
    filesContext: false
    implementationPlan: false
    spec: false

---

Phase 1: Context Detection

steps:
  - id: detect-source
    action: identify_requirement_source
    description: |
      Identificar de onde os requisitos vêm:
      1. PRD existente → extrair requisitos do documento
      2. User input → elicitar via perguntas
      3. Existing spec → iterar sobre spec anterior

Phase 2: Elicitation (if source=user)

CRITICAL: This phase requires user interaction. Do NOT skip.*

elicitation:
  enabled: true
  format: structured-questions
  inspiration: GitHub Spec-Kit 9-category taxonomy

  questions:
    # === Original 5 Categories ===

    - id: q1-what
      category: functional
      question: 'O que o sistema deve FAZER? (funcionalidades principais)'
      follow_ups:
        - 'Quem são os usuários dessa funcionalidade?'
        - 'Qual o trigger/gatilho para essa ação?'

    - id: q2-constraints
      category: constraints
      question: 'Existem RESTRIÇÕES técnicas ou de negócio?'
      examples:
        - 'Tempo máximo de resposta'
        - 'Integrações obrigatórias'
        - 'Limitações de stack'

    - id: q3-nfr
      category: non-functional
      question: 'Requisitos NÃO-FUNCIONAIS importantes?'
      examples:
        - 'Performance (latência, throughput)'
        - 'Segurança (autenticação, autorização)'
        - 'Escalabilidade'

    - id: q4-success
      category: acceptance
      question: 'Como sabemos que está PRONTO? (critérios de aceite)'
      format: given-when-then

    - id: q5-assumptions
      category: assumptions
      question: 'Quais SUPOSIÇÕES estamos fazendo?'
      note: 'Documentar para validação posterior'

    # === New 4 Categories (SDD Adoption) ===

    - id: q6-domain
      category: domain-model
      question: 'Quais ENTIDADES e RELACIONAMENTOS existem?'
      follow_ups:
        - 'Quais são os objetos principais do domínio?'
        - 'Como eles se relacionam entre si?'
        - 'Quais atributos são obrigatórios?'
      examples:
        - 'User has many Orders'
        - 'Product belongs to Category'
        - 'Invoice references Order'

    - id: q7-interaction
      category: interaction-ux
      question: 'Como o USUÁRIO INTERAGE com o sistema?'
      follow_ups:
        - 'Qual o fluxo principal (happy path)?'
        - 'Quais telas ou componentes estão envolvidos?'
        - 'Existem estados de loading, erro, vazio?'
      examples:
        - 'User clicks button → modal opens → form submits → success toast'
        - 'Page loads → fetches data → displays list or empty state'

    - id: q8-edge-cases
      category: edge-cases
      question: 'O que acontece quando algo DÁ ERRADO?'
      follow_ups:
        - 'E se a rede falhar?'
        - 'E se o usuário não tiver permissão?'
        - 'E se os dados estiverem inválidos?'
        - 'E se o serviço externo estiver indisponível?'
      examples:
        - 'Timeout após 30s → retry automático → fallback para cache'
        - 'Validação falha → mostrar erros inline → não submeter'

    - id: q9-terminology
      category: terminology
      question: 'Existe GLOSSÁRIO ou termos específicos do domínio?'
      follow_ups:
        - 'Algum termo tem significado específico neste contexto?'
        - 'Existem sinônimos que devemos padronizar?'
      examples:
        - '"Cliente" vs "Usuário" vs "Account" - qual usar?'
        - '"Pedido" significa Order ou Request neste contexto?'
      note: 'Inconsistência terminológica causa bugs e confusão'

Phase 3: PRD Extraction (if source=prd)

prd_extraction:
  enabled: true

  sections_to_extract:
    - user_stories: 'Extract user stories as functional requirements'
    - acceptance_criteria: 'Map to acceptance array'
    - constraints: 'Technical and business constraints'
    - nfrs: 'Non-functional requirements'

  validation:
    - Ensure all extracted items have clear descriptions
    - Flag ambiguous requirements for clarification
    - Cross-reference with PRD goals

Phase 4: Structuring

structuring:
  action: create_requirements_json

  template: |
    {
      "storyId": "{storyId}",
      "gatheredAt": "{timestamp}",
      "source": "{source}",
      "gatheredBy": "@pm",
      "elicitationVersion": "2.0",

      "functional": [
        {
          "id": "FR-{n}",
          "description": "{requirement}",
          "priority": "P0|P1|P2",
          "rationale": "{why}",
          "acceptance": ["AC-{n}"]
        }
      ],

      "nonFunctional": [
        {
          "id": "NFR-{n}",
          "category": "performance|security|scalability|usability",
          "description": "{requirement}",
          "metric": "{measurable_criteria}"
        }
      ],

      "constraints": [
        {
          "id": "CON-{n}",
          "type": "technical|business|regulatory",
          "description": "{constraint}",
          "impact": "{how_it_affects_solution}"
        }
      ],

      "assumptions": [
        {
          "id": "ASM-{n}",
          "description": "{assumption}",
          "risk_if_wrong": "{impact}",
          "validation_needed": true|false
        }
      ],

      "domainModel": [
        {
          "id": "DM-{n}",
          "entity": "{entity_name}",
          "attributes": ["{attr1}", "{attr2}"],
          "relationships": [
            {
              "type": "has_many|belongs_to|has_one",
              "target": "{other_entity}"
            }
          ]
        }
      ],

      "interactions": [
        {
          "id": "INT-{n}",
          "trigger": "{user_action}",
          "flow": ["{step1}", "{step2}", "{step3}"],
          "states": {
            "loading": "{loading_behavior}",
            "error": "{error_behavior}",
            "empty": "{empty_state}"
          }
        }
      ],

      "edgeCases": [
        {
          "id": "EC-{n}",
          "scenario": "{what_goes_wrong}",
          "handling": "{how_to_handle}",
          "severity": "critical|high|medium|low"
        }
      ],

      "terminology": [
        {
          "term": "{term}",
          "definition": "{meaning_in_this_context}",
          "synonyms": ["{alt1}", "{alt2}"],
          "avoid": ["{term_to_avoid}"]
        }
      ],

      "openQuestions": [
        {
          "id": "OQ-{n}",
          "question": "{question}",
          "blocking": true|false,
          "assignedTo": "@{agent}"
        }
      ]
    }

---

Output Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["storyId", "gatheredAt", "source", "functional"],
  "properties": {
    "storyId": { "type": "string" },
    "gatheredAt": { "type": "string", "format": "date-time" },
    "source": { "enum": ["prd", "user", "existing"] },
    "gatheredBy": { "type": "string", "default": "@pm" },
    "elicitationVersion": { "type": "string", "default": "2.0" },
    "functional": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["id", "description", "priority"],
        "properties": {
          "id": { "type": "string", "pattern": "^FR-\\d+$" },
          "description": { "type": "string", "minLength": 10 },
          "priority": { "enum": ["P0", "P1", "P2"] },
          "rationale": { "type": "string" },
          "acceptance": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "nonFunctional": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "description", "category"],
        "properties": {
          "id": { "type": "string", "pattern": "^NFR-\\d+$" },
          "description": { "type": "string", "minLength": 10 },
          "category": { "enum": ["performance", "security", "scalability", "usability", "reliability"] }
        }
      }
    },
    "constraints": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "description"],
        "properties": {
          "id": { "type": "string", "pattern": "^CON-\\d+$" },
          "description": { "type": "string", "minLength": 10 },
          "type": { "enum": ["technical", "business", "regulatory"] }
        }
      }
    },
    "assumptions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "description"],
        "properties": {
          "id": { "type": "string", "pattern": "^ASM-\\d+$" },
          "description": { "type": "string", "minLength": 10 },
          "risk": { "enum": ["low", "medium", "high"] }
        }
      }
    },
    "domainModel": {
      "type": "array",
      "description": "Entities and relationships (SDD q6)",
      "items": {
        "type": "object",
        "required": ["entity", "description"],
        "properties": {
          "entity": { "type": "string" },
          "description": { "type": "string" },
          "relationships": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "interactions": {
      "type": "array",
      "description": "UX flows and states (SDD q7)",
      "items": {
        "type": "object",
        "required": ["flow", "description"],
        "properties": {
          "flow": { "type": "string" },
          "description": { "type": "string" },
          "states": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "edgeCases": {
      "type": "array",
      "description": "Failure scenarios (SDD q8)",
      "items": {
        "type": "object",
        "required": ["scenario", "handling"],
        "properties": {
          "scenario": { "type": "string" },
          "handling": { "type": "string" },
          "severity": { "enum": ["low", "medium", "high", "critical"] }
        }
      }
    },
    "terminology": {
      "type": "array",
      "description": "Domain glossary (SDD q9)",
      "items": {
        "type": "object",
        "required": ["term", "definition"],
        "properties": {
          "term": { "type": "string" },
          "definition": { "type": "string" },
          "aliases": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "openQuestions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["question"],
        "properties": {
          "question": { "type": "string" },
          "priority": { "enum": ["low", "medium", "high"] },
          "blocksProgress": { "type": "boolean" }
        }
      }
    }
  }
}

---

Command Integration (@pm)

command:
  name: 'gather-requirements'
  syntax: 'gather-requirements {story-id} [--source=prd|user] [--prd=path]'
  agent: pm

  examples:
    - 'gather-requirements STORY-42'
    - 'gather-requirements STORY-42 --source=prd --prd=docs/prd/feature-x.md'

Pipeline Integration

pipeline:
  phase: gather
  next_phase: assess

  pass_to_next:
    - requirements.json

  skip_conditions: [] # Gather is always required

---

Error Handling

errors:
  - id: no-requirements
    condition: 'functional array is empty after elicitation'
    action: 'Re-prompt user for at least one functional requirement'
    blocking: true

  - id: ambiguous-requirement
    condition: 'requirement description < 10 characters'
    action: 'Ask for clarification'
    blocking: false

  - id: missing-acceptance
    condition: 'functional requirement has no acceptance criteria'
    action: 'Generate suggested acceptance criteria for review'
    blocking: false

---

Example 1: User Elicitation

Input:* "Quero adicionar login com Google"

Elicitation:*

Q1: O que o sistema deve FAZER?
→ Permitir que usuários façam login usando conta Google

Q2: Existem RESTRIÇÕES?
→ Deve usar OAuth 2.0, não armazenar senhas

Q3: Requisitos NÃO-FUNCIONAIS?
→ Login deve completar em < 3 segundos

Q4: Como sabemos que está PRONTO?
→ Given usuário na página de login
   When clica em "Login com Google"
   Then é redirecionado para Google OAuth
   And após autorização, está logado no sistema

Output:* docs/stories/STORY-42/spec/requirements.json

---