Idea Processor - Automated Workflow

Automatiza la conversión de ideas en historias de usuario con validación de duplicados

Este sistema automatiza el flujo descrito en el problema: lee ideas del archivo IDEAS.md, valida si son duplicadas o similares a historias de usuario existentes en BACKLOG.md, marca las duplicadas, y genera historias de usuario formales para las ideas únicas.

🎯 Características

✅ Detección de Duplicados: Usa IA (OpenAI o Google Gemini) para detectar similitudes semánticas
✅ Generación Automática: Convierte ideas en historias de usuario siguiendo el template del proyecto
✅ Marcado Automático: Marca ideas duplicadas en IDEAS.md con referencia a la US similar
✅ Actualización de Backlog: Agrega automáticamente nuevas US a BACKLOG.md
✅ Modo Preview: Opción --dry-run para ver cambios sin modificar archivos
✅ Interface Rica: Output con colores y tablas usando Rich
✅ GitHub Actions: Procesamiento automático en cada push a master
✅ Dual AI Support: Compatible con OpenAI y Google Gemini

📋 Requisitos

Software

Python 3.10 o superior
pip (gestor de paquetes de Python)
Cuenta de OpenAI O Google Gemini con API key

Credenciales

OpenAI API Key: Para usar OpenAI (opcional)
Gemini API Key: Para usar Google Gemini (recomendado para GitHub Actions)

🚀 Instalación

1. Instalar Dependencias

# Desde el directorio raíz del proyecto
cd /home/runner/work/architecture-base/architecture-base

# Instalar dependencias del script
pip install -r scripts/idea_processor/requirements.txt

2. Configurar API Keys

Opción A: Usar Google Gemini (Recomendado para GitHub Actions)

# Variable de entorno
export GEMINI_API_KEY='your-gemini-api-key-here'
export AI_PROVIDER='gemini'

# O crear archivo .env en el directorio raíz
cat > .env << EOF
AI_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-api-key-here
GEMINI_MODEL=gemini-1.5-pro
EOF

Para obtener tu Gemini API key:

Visita https://aistudio.google.com/app/apikey
Crea una nueva API key
Copia el valor y configúralo como variable de entorno

Opción B: Usar OpenAI

# Variable de entorno
export OPENAI_API_KEY='sk-your-api-key-here'
export AI_PROVIDER='openai'

# O crear archivo .env
cat > .env << EOF
AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key-here
EOF

Para obtener tu OpenAI API key:

Visita https://platform.openai.com/api-keys
Crea una nueva API key
Copia el valor y configúralo como variable de entorno

📖 Uso

Comando Básico

# Procesar ideas y actualizar archivos
python -m scripts.idea_processor.cli

Modo Preview (Dry Run)

# Ver qué cambios se harían sin modificar archivos
python -m scripts.idea_processor.cli --dry-run

Opciones Avanzadas

# Ajustar umbral de similitud (default: 0.80 = 80%)
python -m scripts.idea_processor.cli --threshold 0.85

# Modo verbose para debugging
python -m scripts.idea_processor.cli --verbose

# Combinar opciones
python -m scripts.idea_processor.cli --dry-run --threshold 0.85 --verbose

Ayuda

python -m scripts.idea_processor.cli --help

🤖 GitHub Actions - Procesamiento Automático

Configuración

El repositorio incluye un workflow de GitHub Actions que procesa ideas automáticamente en cada push a la rama master que modifique el archivo IDEAS.md.

Archivo: .github/workflows/process-ideas-gemini.yml

Paso 1: Configurar Secret en GitHub

Ve a tu repositorio en GitHub
Settings → Secrets and variables → Actions
Click en "New repository secret"
Nombre: GEMINI_API_KEY
Valor: Tu API key de Google Gemini
Click en "Add secret"

Paso 2: Activar el Workflow

El workflow se activa automáticamente cuando:

Haces push a la rama master o main
El archivo IDEAS.md ha sido modificado

Qué Hace el Workflow

✅ Instala Python y dependencias
✅ Ejecuta el procesador de ideas con Gemini AI
✅ Detecta duplicados y genera user stories
✅ Commitea y pushea cambios automáticamente
✅ Crea un resumen en la pestaña Actions

Ejemplo de Uso

# 1. Agregar ideas a IDEAS.md
vim IDEAS.md
# Agrega tu idea con estado "💭 Por refinar"

# 2. Commit y push
git add IDEAS.md
git commit -m "feat: add new idea for caching"
git push origin master

# 3. El workflow se ejecuta automáticamente
# Ve a la pestaña "Actions" en GitHub para ver el progreso

# 4. Revisa los cambios
git pull
# Verás IDEAS.md actualizado y nuevas US en BACKLOG.md

Ver Resultados

Pestaña Actions: Ve el log completo de ejecución
Commits: El bot crea commits con el formato "🤖 Auto-process ideas..."
Summary: Cada ejecución genera un resumen de cambios

Desactivar el Workflow

Si prefieres ejecutar manualmente:

# Opción 1: Eliminar el archivo
rm .github/workflows/process-ideas-gemini.yml

# Opción 2: Deshabilitar en GitHub
# Settings → Actions → Selecciona el workflow → Disable workflow

🔄 Flujo de Trabajo

Diagrama del Proceso

┌─────────────┐
│  IDEAS.md   │
│  (Captura)  │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────┐
│  1. Parse Ideas & User Stories  │
└──────┬──────────────────────────┘
       │
       ▼
┌─────────────────────────────────┐
│  2. Check Similarity with AI    │
│     - Use embeddings            │
│     - Compare semantically      │
└──────┬──────────────────────────┘
       │
       ├─────────────┬──────────────┐
       ▼             ▼              ▼
  ┌─────────┐  ┌─────────┐   ┌──────────┐
  │Duplicate│  │Duplicate│   │  Unique  │
  │ (US-XX) │  │ (ID-XX) │   │   Idea   │
  └────┬────┘  └────┬────┘   └────┬─────┘
       │            │              │
       ▼            ▼              ▼
  ┌──────────────────────┐   ┌─────────────────┐
  │ Mark as Duplicate    │   │ Generate US     │
  │ in IDEAS.md          │   │ using GPT-4     │
  └──────────────────────┘   └────┬────────────┘
                                   │
                                   ▼
                            ┌──────────────────┐
                            │ Append to        │
                            │ BACKLOG.md       │
                            └──────────────────┘
                                   │
                                   ▼
                            ┌──────────────────┐
                            │ Mark as          │
                            │ Converted in     │
                            │ IDEAS.md         │
                            └──────────────────┘

Paso a Paso

Carga de Archivos
- Lee IDEAS.md y parsea todas las ideas
- Lee BACKLOG.md y parsea todas las historias de usuario existentes
Filtrado
- Identifica ideas con estado "💭 Por refinar"
- Estas son las ideas candidatas para procesamiento
Detección de Duplicados
- Para cada idea candidata:
  - Genera embedding (vector) del texto completo
  - Compara con embeddings de todas las US existentes
  - Compara con otras ideas
  - Si similitud > threshold (default 80%):
    - Usa GPT-4 para análisis semántico detallado
    - Obtiene score de similitud y razón
    - Marca como duplicada si score > threshold
Generación de User Stories
- Para cada idea única (no duplicada):
  - Usa GPT-4 para generar historia de usuario formal
  - Sigue el formato del template (docs/backlog-template.md)
  - Genera: título, Como/Quiero/Para, criterios de aceptación, estimación, etc.
  - Asigna ID secuencial (US-XXX)
Actualización de Archivos
- IDEAS.md:
  - Marca duplicadas: **Estado**: ⚠️ Repetida - Similar a US-XXX (similitud: 85%)
  - Marca convertidas: **Estado**: ✅ Convertida a US-XXX
- BACKLOG.md:
  - Agrega nuevas US en la sección de prioridad correspondiente
  - Mantiene formato y estructura existente

📁 Estructura del Código

scripts/idea_processor/
├── __init__.py           # Package init
├── cli.py                # Command-line interface
├── config.py             # Configuration settings
├── models.py             # Data models (Idea, UserStory, etc.)
├── parser.py             # Markdown parser
├── similarity.py         # Similarity checker with OpenAI
├── generator.py          # User story generator
├── processor.py          # Main workflow orchestrator
├── requirements.txt      # Python dependencies
└── README.md            # This file

⚙️ Configuración

Archivo `config.py`

Puedes ajustar la configuración editando scripts/idea_processor/config.py:

class Config(BaseModel):
    # Paths (auto-detectados)
    repo_root: Path
    ideas_file: Path
    backlog_file: Path
    
    # OpenAI
    openai_model: str = "gpt-4o"
    embedding_model: str = "text-embedding-3-small"
    
    # Similarity threshold
    similarity_threshold: float = 0.80  # 80%
    
    # Output
    verbose: bool = True
    dry_run: bool = False

Variables de Entorno

Puedes usar un archivo .env en el directorio raíz:

# .env
OPENAI_API_KEY=sk-your-api-key-here

📊 Output Ejemplo

Preview Mode (--dry-run)

🚀 Idea Processor Initialized

⚠️  Running in DRY RUN mode - no files will be modified

Step 1: Loading files...

Step 2: Parsing ideas and user stories...

✓ Found 6 ideas
✓ Found 10 existing user stories

📝 Ideas to process: 6

Step 3: Checking for duplicates...

Checking ID-001: Dashboard de Métricas en Tiempo Real
  ✓ Unique idea

Checking ID-002: Sistema de Retry Inteligente para Eventos
  ⚠️  Duplicate found - Similar to US-003 (score: 0.87)
  └─ Reason: Ambas tratan sobre manejo de eventos fallidos...

...

┌──────────────────────────────────────────────────┐
│          ⚠️  Duplicate Ideas Found               │
├──────────┬──────────────────────┬────────────────┤
│ Idea ID  │ Title                │ Similar To     │
├──────────┼──────────────────────┼────────────────┤
│ ID-002   │ Sistema de Retry...  │ US-003  (87%)  │
└──────────┴──────────────────────┴────────────────┘

Step 4: Generating user stories from 5 unique ideas...

Generating user story for ID-001...
  ✓ Generated US-011: Dashboard de Métricas en Tiempo Real

...

┌────────────────────────────────────────────────────┐
│          ✨ Generated User Stories                 │
├───────┬──────────────────────┬──────────┬─────────┤
│ US ID │ Title                │ Priority │ Points  │
├───────┼──────────────────────┼──────────┼─────────┤
│US-011 │ Dashboard de Mét...  │ Alta 🔴  │   8     │
│US-012 │ Versionado Auto...   │ Media 🟡 │   5     │
└───────┴──────────────────────┴──────────┴─────────┘

┌──────────────────────────────────────────────────┐
│                    Summary                        │
├──────────────────────────────────────────────────┤
│ 📊 Processing Complete!                          │
│                                                   │
│ Duplicate Ideas Found: 1                         │
│ New User Stories Generated: 5                    │
│                                                   │
│ Next Steps:                                      │
│ 1. Review generated user stories in BACKLOG.md  │
│ 2. Check marked duplicate ideas in IDEAS.md     │
│ 3. Refine user stories as needed                │
└──────────────────────────────────────────────────┘

Note: This was a dry run. No files were modified.
Run without --dry-run to apply changes.

🧪 Testing

Test Manualmente

Dry Run First

python -m scripts.idea_processor.cli --dry-run

Verificar Output
- Revisa que las ideas detectadas como duplicadas sean correctas
- Verifica que las historias generadas tengan sentido
Aplicar Cambios
```
python -m scripts.idea_processor.cli
```

Verificar Archivos

# Ver cambios en IDEAS.md
git diff IDEAS.md

# Ver cambios en BACKLOG.md
git diff BACKLOG.md

Test con Ideas de Ejemplo

El script funciona con las ideas existentes en IDEAS.md. Puedes agregar ideas de prueba:

### [ID-999] Test Idea

- **Contexto**: Testing del sistema
- **Problema**: Validar el flujo automatizado
- **Valor**: Asegurar que funciona correctamente
- **Fecha**: 2025-11-14
- **Estado**: 💭 Por refinar

🔧 Troubleshooting

Error: "OpenAI API key not found"

Solución: Asegúrate de que la variable de entorno esté configurada:

export OPENAI_API_KEY='sk-your-key-here'

Error: "File not found: IDEAS.md"

Solución: Ejecuta el script desde el directorio raíz del proyecto:

cd /path/to/architecture-base
python -m scripts.idea_processor.cli

Error: "Module not found"

Solución: Instala las dependencias:

pip install -r scripts/idea_processor/requirements.txt

Similitud incorrecta

Solución: Ajusta el threshold:

# Más estricto (menos falsos positivos)
python -m scripts.idea_processor.cli --threshold 0.90

# Menos estricto (más sensible)
python -m scripts.idea_processor.cli --threshold 0.75

💰 Costos de OpenAI

Estimación por Ejecución

Para procesar 6 ideas:

Embeddings: ~$0.001 por idea × 6 = $0.006
GPT-4 para similitud: ~$0.01 por comparación × 6 = $0.06
GPT-4 para generación de US: ~$0.02 por US × 5 = $0.10

Total estimado: ~$0.17 por ejecución

Optimización de Costos

Usar --dry-run primero: Valida la lógica sin gastar en generación
Ajustar threshold: Evita comparaciones innecesarias
Procesar por lotes: Agrupa ideas para procesar menos frecuentemente

🔐 Seguridad

Buenas Prácticas

No commitar API keys:

# Agrega .env al .gitignore
echo ".env" >> .gitignore

Usar variables de entorno:
- Mejor que hardcodear en código
- Fácil de rotar
Limitar permisos de API key:
- En OpenAI dashboard, limita la API key a solo los modelos necesarios

📚 Recursos Relacionados

BACKLOG.md - Backlog del proyecto
IDEAS.md - Archivo de ideas
docs/backlog-template.md - Template de US
docs/guides/idea-to-task-flow.md - Flujo completo

🤝 Contribuir

Para agregar features o mejorar el script:

Crea una branch
Implementa cambios en scripts/idea_processor/
Prueba con --dry-run
Actualiza este README si es necesario
Crea PR

📝 Changelog

v1.0.0 (2025-11-14)

Implementación inicial
Detección de duplicados con embeddings
Generación automática de user stories
CLI con rich output
Modo dry-run

📄 Licencia

Este script es parte del proyecto architecture-base y sigue la misma licencia del proyecto principal.

FilesExpand file tree

README.md

Latest commit

History