added debugger phylosophy

docs/debugger/README.md

@@ -0,0 +1,113 @@
+# Especificação — Ciclo de Desenvolvimento Prometeu
+**Versão:** 0.1  
+**Status:** Conceitual / Filosófico
+
+---
+
+## 1. Princípio Central
+
+O Prometeu é uma plataforma didática de desenvolvimento de software interativo.  
+Seu ciclo de desenvolvimento é projetado para separar claramente:
+
+- Criação de código
+- Compilação
+- Execução
+- Observação e explicação
+
+Cada etapa possui uma ferramenta própria, especializada e não sobreposta.
+
+---
+
+## 2. Ferramentas do Ciclo
+
+O ciclo utiliza quatro pilares:
+
+1. **Editor de Código**  
+   Ambiente livre (ex: WebStorm) onde o desenvolvedor escreve em TypeScript.
+
+2. **Compilador Prometeu**  
+   Converte código fonte em bytecode executável pela runtime Prometeu.
+
+3. **Runtime Prometeu**  
+   Executa jogos e aplicações em seu próprio ambiente gráfico.
+
+4. **Prometeu Debugger**  
+   Ferramenta didática de observação, análise e explicação do comportamento interno do sistema.
+
+Nenhuma dessas ferramentas tenta substituir a outra.  
+Elas cooperam através de contratos claros.
+
+---
+
+## 3. Fluxo Geral
+
+O ciclo segue sempre a mesma sequência conceitual:
+
+1. O desenvolvedor escreve código em TypeScript.
+2. O código é compilado para bytecode Prometeu.
+3. O bytecode é empacotado como cartucho.
+4. O cartucho é executado pela runtime.
+5. O comportamento interno pode ser observado pelo Prometeu Debugger.
+
+---
+
+## 4. Modos de Execução
+
+O Prometeu possui dois modos conceituais de execução:
+
+### Execução Normal (Run)
+
+- O cartucho é empacotado e executado.
+- A runtime funciona de forma autônoma.
+- O Debugger atua apenas como observador.
+
+### Execução Assistida (Debug)
+
+- O cartucho é empacotado e executado.
+- A runtime aguarda conexão do Prometeu Debugger.
+- O Debugger passa a controlar e observar a execução.
+
+---
+
+## 5. Separação de Papéis
+
+Cada parte do ciclo tem responsabilidade única:
+
+| Etapa     | Papel principal                    |
+|-----------|--------------------------------------|
+| Editor    | Criar código                         |
+| Compilador| Transformar código em bytecode       |
+| Runtime   | Executar                             |
+| Debugger  | Observar, explicar e ensinar         |
+
+Essa separação é intencional e parte da filosofia do Prometeu.
+
+---
+
+## 6. Filosofia Didática
+
+O Prometeu não é apenas uma engine.  
+Ele é uma plataforma para aprender como software interativo funciona por dentro.
+
+O ciclo de desenvolvimento é pensado para:
+
+- Tornar a execução visível
+- Tornar decisões técnicas observáveis
+- Tornar erros explicáveis
+- Tornar desempenho mensurável
+
+O Debugger não é apenas uma ferramenta de correção, mas um instrumento pedagógico.
+
+---
+
+## 7. Síntese
+
+O Ciclo de Desenvolvimento Prometeu é:
+
+- Modular
+- Observável
+- Didático
+- Não acoplado a uma IDE específica
+- Orientado a aprendizado e compreensão profunda
+
+Ele existe para que o desenvolvedor não apenas escreva programas, mas entenda como eles vivem dentro da máquina.