Requerimientos con IA

# Master Prompt: Interrogatorio Estructurado de Specs

> **Qué es:** Un system prompt listo para usar que convierte a cualquier asistente de IA (Claude, ChatGPT, Gemini) en un interrogador estructurado de especificaciones.
> **Cuándo usarlo:** Cada vez que tengas un spec o PR/FAQ en borrador y quieras detectar ambigüedades, vacíos y supuestos ocultos antes de compartirlo con el equipo.
> **Cómo usarlo:** Copia el bloque "System Prompt" completo al inicio de tu sesión de IA, luego pega tu spec y sigue las 5 fases en orden.

---

## System Prompt

```
Eres un asistente de producto especializado en interrogatorio estructurado de especificaciones.
Tu función es ayudarme a validar, completar y mejorar un documento de especificación de producto (PR/FAQ o Spec).

Debes seguir estas reglas:

1. **Contexto Cero:** El único contexto disponible es el documento que voy a pegarte a continuación. No inventes características, usuarios o casos de uso que no estén descritos.
2. **No asumas:** Si algo no está especificado, pregúntame antes de asumir. No completes información faltante con lo que "tiene sentido".
3. **Sé estructurado:** Organiza tus respuestas por secciones del spec. Usa listas numeradas y viñetas.
4. **Sé específico:** No digas "hay ambigüedad". Señala exactamente qué línea, qué palabra, y por qué es ambigua.
5. **Identifica silencios:** Señala no solo lo que está mal, sino lo que NO está en el spec y debería estar.
```

## Preguntas de Interrogatorio por Fase

### Fase 1 — Completitud

```
Revisa este spec y responde:

1. ¿Qué secciones del template están vacías o incompletas?
2. ¿Hay marcadores [PENDIENTE], TBD o [NEEDS CLARIFICATION] sin resolver?
3. ¿Los criterios de éxito son medibles? Si no, ¿cuáles no lo son?
4. ¿Los casos borde cubren al menos 3 escenarios de fallo?
5. ¿Hay una sección "Lo que NO está incluido"? Si no, créala.
```

### Fase 2 — Ambigüedad

```
Ahora identifica ambigüedades:

1. ¿Hay términos subjetivos sin definir ("mejorar", "optimizar", "rápido", "fácil")?
2. ¿Hay requisitos que dependen de interpretación personal?
3. ¿Hay frases que dos personas podrían entender de forma diferente?
4. ¿Hay números o métricas sin unidad de medida?
5. ¿Hay referencias a cosas que no existen en el spec?
```

### Fase 3 — Generación de Backlog

```
Basado exclusivamente en este spec, genera:

1. Las 5-10 historias de usuario necesarias para implementar esta feature.
2. Para cada historia: criterio de aceptación claro.
3. El orden de implementación sugerido (dependencias entre historias).
4. ¿Qué historias podrían dividirse en tareas más pequeñas?
```

### Fase 4 — Interrogatorio Cruzado

```
Actúa ahora como un stakeholder escéptico que no quiere esta feature.
Haz las 5 preguntas más difíciles que podrían hacerte en un comité de aprobación.
Para cada pregunta, dime si el spec actual la responde o no.
```

### Fase 5 — Versión Mejorada

```
Genera una versión mejorada del spec completo incorporando las correcciones
identificadas en las fases anteriores. Marca con [MODIFICADO] todo lo que cambiaste
respecto al original para que pueda revisar los cambios.
```

#!/bin/bash
# ============================================================
# interrogar-spec.sh — Interrogar un spec con IA desde terminal
# ============================================================
# Qué es:      Envía tu spec + una pregunta a la API de OpenAI
#              y devuelve la respuesta basada solo en el spec.
# Cuándo usarlo: Para validar specs en lote o integrarlo en un
#              flujo automatizado (sin abrir el chat web).
# Requisitos:  - OPENAI_API_KEY exportada: export OPENAI_API_KEY="sk-..."
#              - jq instalado: sudo apt install jq / brew install jq
# Cómo usarlo: chmod +x interrogar-spec.sh
#              ./interrogar-spec.sh spec.md "¿Qué ambigüedades tiene este spec?"
# ============================================================

SPEC_FILE=$1
PREGUNTA="$2"

if [ -z "$SPEC_FILE" ] || [ -z "$PREGUNTA" ]; then
    echo "Uso: $0 <archivo-spec.md> <pregunta>"
    echo "Ej: $0 spec.md 'Genera el backlog para esta feature'"
    exit 1
fi

CONTENIDO=$(cat "$SPEC_FILE")

curl -s https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d "{
    \"model\": \"gpt-4o\",
    \"messages\": [
      {\"role\": \"system\", \"content\": \"Eres un asistente de producto. Debes responder basándote exclusivamente en el contexto proporcionado. Si algo no está definido, menciónalo.\"},
      {\"role\": \"user\", \"content\": \"Contexto:\n$CONTENIDO\n\nPregunta:\n$PREGUNTA\"}
    ]
  }" | jq '.choices[0].message.content'

#!/usr/bin/env pwsh
# ============================================================
# interrogar-spec.ps1 — Interrogar un spec con IA (Windows)
# ============================================================
# Qué es:      Versión PowerShell de interrogar-spec.sh — envía
#              tu spec + una pregunta a la API de OpenAI.
# Cuándo usarlo: Para validar specs desde Windows sin WSL.
# Requisitos:  OPENAI_API_KEY configurada:
#              $env:OPENAI_API_KEY = "sk-..."
# Cómo usarlo: .\interrogar-spec.ps1 spec.md "¿Qué ambigüedades tiene este spec?"
# ============================================================

param(
    [Parameter(Mandatory=$true)][string]$SpecFile,
    [Parameter(Mandatory=$true)][string]$Pregunta
)

$OPENAI_API_KEY = $env:OPENAI_API_KEY
if (-not $OPENAI_API_KEY) {
    Write-Error "OPENAI_API_KEY no está configurada"
    exit 1
}

$CONTENIDO = Get-Content -Path $SpecFile -Raw

$body = @{
    model = "gpt-4o"
    messages = @(
        @{
            role = "system"
            content = "Eres un asistente de producto. Debes responder basándote exclusivamente en el contexto proporcionado. Si algo no está definido, menciónalo."
        }
        @{
            role = "user"
            content = "Contexto:`n$CONTENIDO`n`nPregunta:`n$Pregunta"
        }
    )
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "https://api.openai.com/v1/chat/completions" `
    -Method POST `
    -Headers @{ "Authorization" = "Bearer $OPENAI_API_KEY" } `
    -ContentType "application/json" `
    -Body $body

$response.choices[0].message.content

# Ejemplos de cURL para APIs de IA

> **Qué es:** Referencia rápida de llamadas cURL a APIs de IA, listas para copiar, pegar y adaptar desde la terminal.
> **Cuándo usarlo:** Cuando quieras probar un prompt o automatizar una consulta sin abrir el playground ni escribir código.
> **Requisitos:** `curl` y `jq` instalados, y tu API key en una variable de entorno (ej. `export OPENAI_API_KEY="sk-..."`).

## OpenAI — Chat Completion

```bash
# Consulta básica
curl -s https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Escribe una user story para un login biométrico"}
    ]
  }' | jq '.choices[0].message.content'
```

```bash
# Con system prompt
curl -s https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "Eres un PM experto en salud. Responde con formato PR/FAQ."},
      {"role": "user", "content": "Diseña una función de agenda inteligente para pacientes crónicos"}
    ]
  }' | jq '.choices[0].message.content'
```

```bash
# Con temperatura controlada (0.0 = determinista, 1.0 = creativo)
curl -s https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "temperature": 0.2,
    "messages": [
      {"role": "user", "content": "Genera 3 criterios de aceptación para: como operador quiero recibir una alerta cuando un insumo crítico baje del stock mínimo"}
    ]
  }' | jq '.choices[0].message.content'
```

## Anthropic — Claude

```bash
# Consulta básica
curl -s https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Analiza este spec y encuentra edge cases no cubiertos: [pega tu spec aquí]"}
    ]
  }' | jq '.content[0].text'
```

```bash
# Con mucho contexto (spec completo)
curl -s https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 2048,
    "messages": [
      {"role": "user", "content": "Contexto:\n'"$(cat spec.md)"'\n\nPregunta: ¿Qué riesgos de implementación ves?"}
    ]
  }' | jq '.content[0].text'
```

## Respuestas estructuradas (modo JSON)

```bash
curl -s https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "response_format": { "type": "json_object" },
    "messages": [
      {"role": "user", "content": "Genera un backlog JSON con 5 tareas priorizadas para: implementar un módulo de trazabilidad de lotes"}
    ]
  }' | jq '.choices[0].message.content | fromjson'
```

## Tips

| Problema | Solución |
|----------|----------|
| `curl: command not found` | Instalar curl: `sudo apt install curl` / `brew install curl` |
| `jq: command not found` | Instalar jq: `sudo apt install jq` / `brew install jq` |
| `API key not set` | Exportar variable: `export OPENAI_API_KEY="sk-..."` |
| Error 401 | La API key es inválida o expiró |
| Error 429 | Rate limit excedido — esperar o reducir frecuencia |
| Respuesta truncada | Aumentar `max_tokens` en el request |