# Entenda o problema/oportunidade:
- Qual dor o usuário/negócio está sentindo?
- Qual oportunidade estamos perdendo?
- O que acontece se NÃO fizermos isso?
- Qual o impacto esperado?

# Faça perguntas clarificadoras:
- Quem é o usuário afetado?
- Qual o volume/escala esperado?
- Há constraints de tempo, custo, ou tecnologia?

# Liste mudanças propostas de forma concisa:
- O que será adicionado?
- O que será modificado?
- O que será removido?
- Há breaking changes?

# Identifique affected specs:
- Quais capabilities em specs/ serão afetadas?
- Há novas capabilities a criar?

# Identifique affected code:
- Quais bounded contexts serão afetados?
- Quais módulos/componentes?

# Avalie a complexidade da mudança:

LOW:
- Mudança simples, poucos arquivos (<5)
- Um único bounded context
- Padrões já estabelecidos no projeto
- Sem design significativo necessário
- Exemplo: adicionar validação de campo, novo endpoint CRUD

MEDIUM:
- Mudança moderada, múltiplos arquivos (5-15)
- Múltiplos componentes dentro de um bounded context
- Alguns padrões novos, mas arquitetura clara
- Design leve pode ajudar
- Exemplo: nova feature com 3-5 use cases, integração simples

HIGH:
- Mudança significativa, muitos arquivos (>15)
- Múltiplos bounded contexts ou integrações externas
- Decisões arquiteturais importantes
- Trade-offs técnicos a avaliar
- Requer fase de Architecture (design.md)
- Exemplo: sistema de pagamento, autenticação, mensageria

# Verifique se há quebra de compatibilidade:

Breaking changes podem ser:
- Mudança em API pública (endpoints, request/response)
- Mudança em database schema (remove columns, change types)
- Mudança em contratos de integração
- Remoção de features existentes

Se breaking:
- Documente o que quebra
- Defina migration guide
- Defina timeline de deprecação

# Decida o fluxo:

Complexity = LOW ou MEDIUM:
→ Prosseguir para Phase 3 (Specification) diretamente
→ Skip Phase 2 (Architecture)

Complexity = HIGH:
→ Requer Phase 2 (Architecture) antes de Specification
→ Architect criará design.md com ADRs, C4 diagrams, DDD design

# Read relevant context:
- User request/issue
- specs/ (quality rules, architectural principles) (principles)
- specs/ (existing capabilities)
- src/ (current architecture, optional)

# Location:
changes/[change-id]/proposal.md

# Use template:
.claude/templates/proposal.md

# Submeter proposal.md para:
- Product Owner (se mudança de negócio)
- Tech Lead (sempre)
- Team (para awareness)

# Aguardar aprovação antes de prosseguir

# Para cada capability afetada, criar ou atualizar:
specs/[capability]/spec.md

# Seguir formato:
- Arc42 (adaptive by complexity)
- C4 Model (diagrams)
- BDD Scenarios (GIVEN-WHEN-THEN)
- ADRs (if not covered by design.md)
- OpenSpec Delta format (ADDED/MODIFIED/REMOVED/RENAMED)

# LOW Complexity - Mínimo obrigatório:
- Chapter 6: Runtime View (comportamento)
- Chapter 10: Quality Requirements (requisitos)

# MEDIUM Complexity - Expandido:
- Chapter 3: Context & Scope
- Chapter 5: Building Blocks (estrutura)
- Chapter 6: Runtime View
- Chapter 8: Concepts (patterns)
- Chapter 9: Architecture Decisions (ADRs se não em design.md)
- Chapter 10: Quality Requirements

# HIGH Complexity - Completo:
- Todos 12 chapters do Arc42
- Referência design.md para decisões arquiteturais

# Para cada requirement, escrever scenarios BDD:

Feature: [Nome da Feature]

Background:
  [Contexto comum a todos scenarios]

Scenario: [Nome do Scenario - Happy Path]
  Given [pré-condição clara e específica]
    And [pré-condição adicional se necessário]
  When [ação do usuário ou sistema]
    And [ação adicional se necessário]
  Then [resultado esperado verificável]
    And [resultado adicional]
    And [side effect: event, notification, etc]

Scenario: [Nome do Scenario - Error Case]
  Given [pré-condição que leva a erro]
  When [ação que trigga erro]
  Then [erro específico é retornado]
    And [mensagem user-friendly]
    And [estado do sistema preservado]

# Guidelines:
- Scenarios devem ser executáveis (podem virar integration tests)
- Use linguagem de negócio (ubiquitous language)
- Seja específico em dados (não "algum", "qualquer", "vários")
- Cada scenario testa UMA coisa
- Cubra happy paths e error cases

# Para cada elemento da spec, marcar:

## ADDED: [Section Name]
[Conteúdo novo que não existia antes]

## MODIFIED: [Section Name]
**Before**:
[Como era antes]

**After**:
[Como fica depois]

**Reason**:
[Por que mudou]

## REMOVED: [Section Name]
**Before**:
[O que existia]

**Reason**:
[Por que foi removido]

## RENAMED: [Section Name]
**Before**: [old-name]
**After**: [new-name]
**Reason**: [Justificativa]

# Required:
- changes/[change-id]/proposal.md (full)
- specs/ (quality rules, architectural principles) (full)
- specs/[capability]/spec.md (if updating existing)

# Optional:
- changes/[change-id]/design.md (if HIGH complexity)
- src/[bounded-context]/ (to understand current state)

# Create new spec:
mkdir -p specs/[capability-name]
touch specs/[capability-name]/spec.md

# Use Arc42 structure
# Start with template (can be created if needed)

# Update existing spec:
specs/[capability-name]/spec.md

# Apply delta format:
# - Mark ADDED sections
# - Mark MODIFIED sections (show before/after)
# - Mark REMOVED sections
# - Mark RENAMED sections

# For each requirement, write comprehensive scenarios

# Example:
Feature: User Registration

Background:
  Given the system is running
    And the database is empty

Scenario: Register new user with valid data
  Given a valid email "user@example.com"
    And a valid password "SecurePass123!"
    And a valid name "João Silva"
  When I send POST /api/v1/users with this data
  Then the response status is 201 Created
    And the response contains the user ID
    And the user is stored in the database
    And the event "UsuarioCriado" is published
    And a welcome email is sent to "user@example.com"

Scenario: Reject registration with duplicate email
  Given a user already exists with email "user@example.com"
  When I send POST /api/v1/users with email "user@example.com"
  Then the response status is 409 Conflict
    And the response contains error code "EMAIL_ALREADY_EXISTS"
    And the response contains message "Email já está em uso"
    And no new user is created
    And no event is published

Scenario: Reject registration with invalid email format
  Given an invalid email "not-an-email"
  When I send POST /api/v1/users with this email
  Then the response status is 422 Unprocessable Entity
    And the response contains error code "INVALID_EMAIL"
    And the response contains message "Email inválido"

# Cover:
# - Happy paths (main flow)
# - Error cases (validation, business rules, technical errors)
# - Edge cases (empty, null, boundary values)
# - Side effects (events, notifications, logs)

# Se updating existing spec, aplique delta format:

Example:

## MODIFIED: 6.1 User Registration Flow

**Before**:
User registration only required email and password.

**After**:
User registration now requires email, password, name, and CPF.
CPF is validated using Validator service.

**Reason**:
LGPD compliance requires full name and CPF for brazilian users.

**BDD Scenarios Affected**:
- Scenario "Register with valid data" - MODIFIED (added CPF field)
- Scenario "Reject registration with invalid CPF" - ADDED

# Self-validation checklist:

Arc42 Compliance:
- [ ] Required chapters present (based on complexity)?
- [ ] Chapters have meaningful content (not placeholder)?
- [ ] References design.md if HIGH complexity?

BDD Scenarios:
- [ ] Each requirement has >= 1 scenario?
- [ ] Happy paths covered?
- [ ] Error cases covered?
- [ ] Scenarios are specific (no vague terms)?
- [ ] Scenarios are executable (clear GIVEN-WHEN-THEN)?
- [ ] Side effects documented (events, notifications)?

Delta Format:
- [ ] All changes marked (ADDED/MODIFIED/REMOVED/RENAMED)?
- [ ] MODIFIED sections show before/after?
- [ ] Reasons for changes documented?

Constitution Compliance:
- [ ] Follows Arc42 + C4 + BDD + ADR foundation?
- [ ] DDD Tactical structure respected?
- [ ] Test-First considerations documented?

Quality:
- [ ] Spec is clear and unambiguous?
- [ ] Technical and business stakeholders can understand?
- [ ] Ready for task decomposition (Phase 3.5)?

# Submit spec.md for validation:
- Gatekeeper validates Gate 2: Specification Format
- Automated checks: Arc42 compliance, BDD format, Delta format
- If rejected: fix issues and resubmit
- If approved: proceed to Phase 3.5 (Task Decomposition)

# Specific, executable, testable
Scenario: Register user with valid CPF
  Given a valid CPF "123.456.789-00"
    And a valid email "user@example.com"
  When I register a new user
  Then the user is created with ID
    And the event "UsuarioCriado" is published
    And a welcome email is sent

# Vague, not executable, not testable
Scenario: Register user
  Given some valid data
  When user registers
  Then it works

# Proposal: add-email-validation

## Why
Users can currently register with invalid email formats, causing delivery failures.

## What Changes
- [x] Add email format validation in criar-usuario.ts
- [x] Return 422 error for invalid emails

## Impact
- Affected specs: specs/user-management/
- Affected code: src/user-management/api/usuario/
- Complexity: LOW
- Breaking: NO

## Next Steps
- Requires Design Phase: NO
- Proceed to Specification (Phase 3)

# Proposal: add-payment-gateway

## Why
We need to accept credit card payments to monetize the platform.

## What Changes
- [x] Integrate with Stripe API
- [x] Add payment bounded context
- [x] Implement webhook handling
- [x] Add transaction history
- [x] BREAKING: Add payment_status to orders

## Impact
- Affected specs: specs/payments/ (NEW), specs/orders/ (MODIFIED)
- Affected code: src/payments/ (NEW), src/orders/ (MODIFIED)
- Complexity: HIGH
- Breaking: YES (adds required field to orders)

## Next Steps
- Requires Design Phase: YES
  - Need to decide: Stripe vs PayPal vs Mercado Pago
  - Need to design: Event-driven architecture for webhooks
  - Need to define: Retry strategy, security, PCI compliance
- Proceed to Architecture (Phase 2)