Fase 2: seeds de los 6 buckets (294 ejemplos: penpot 41, otros_mcps 102, skills_adherencia 55, delegacion_subagentes 25, negativos 46, manejo_errores 25)

data/schemas/SEED_FORMAT.md

@@ -0,0 +1,74 @@
+# Formato de seeds para el dataset de entrenamiento (Fase 2)
+
+Referencia común para escribir `data/raw/seeds/<bucket>.jsonl`. Cada linea es un JSON
+independiente (JSONL, `ensure_ascii=False`), con esta forma:
+
+```json
+{
+  "messages": [
+    {"role": "system", "content": "..."},
+    {"role": "user", "content": "..."},
+    {"role": "assistant", "content": "", "reasoning_content": "...", "tool_calls": [
+      {"id": "call_1", "type": "function", "function": {"name": "tool_name", "arguments": {"param": "valor"}}}
+    ]},
+    {"role": "tool", "tool_call_id": "call_1", "name": "tool_name", "content": "resultado o error como texto plano"},
+    {"role": "assistant", "content": "respuesta final visible al usuario", "reasoning_content": "razonamiento del turno final"}
+  ],
+  "tools": [ /* subset de definiciones de tools realmente usadas en este ejemplo, mismo formato que data/schemas/*.json: {name, description, parameters} */ ],
+  "meta": {"bucket": "nombre-del-bucket"}
+}
+```
+
+## Reglas de formato (obligatorias, no negociables)
+
+- **`tool_calls.function.arguments` es SIEMPRE un dict JSON**, nunca un string, nunca XML
+  escrito a mano (`<tool_call><function=...>`). El chat template real de produccion usa
+  XML tipo Hermes, pero eso lo genera `apply_chat_template` automaticamente a partir de
+  este formato dict — nunca lo escribimos nosotros. Ver `06_validate_dataset.py`.
+- **`reasoning_content` es un campo separado**, nunca metas `<think>...</think>` dentro de
+  `content`. Todo turno `assistant` (tenga o no `tool_calls`) debe traer `reasoning_content`
+  con el razonamiento real de ese turno (puede ser breve, pero debe existir y ser genuino,
+  no un placeholder vacio).
+- El primer turno `assistant` de una trayectoria con tool calling debe traer
+  `"content": ""` (el contenido visible va vacio cuando hay `tool_calls`; el texto que el
+  usuario ve al final va en el ULTIMO turno assistant, sin `tool_calls`).
+- Cada `tool` message necesita `tool_call_id` que matchee el `id` del `tool_calls` que lo
+  origino, y `name` con el nombre exacto de la tool.
+- Si un ejemplo no usa ninguna tool (bucket de negativos, o parte de skills/errores que no
+  llama nada), omite el campo `tools` o dejalo `[]`, y no incluyas ningun turno `tool`.
+- `tools` en cada ejemplo es un ARRAY con las definiciones REALES tomadas de
+  `data/schemas/{penpot,gitea,github-personal,docmost,atlassian}.json` — copia el objeto
+  `{name, description, parameters}` tal cual (podes recortar la `description` si es muy
+  larga, pero el `parameters` JSON Schema no se inventa ni se simplifica).
+- **Nunca inventes tools o parametros que no existen en los schemas reales.** Si dudas,
+  Lee el `.json` correspondiente antes de escribir el ejemplo.
+- `system` message es opcional (usalo cuando el ejemplo necesita contexto de skill/tarea
+  para tener sentido), pero no es obligatorio en todos los ejemplos.
+- Cada linea debe ser JSON valido de una sola linea (sin saltos de linea reales dentro del
+  string — usa `\n` escapado si el contenido necesita multi-linea, como reportes de Docmost).
+- No repitas la misma pregunta/situacion literal entre ejemplos del mismo bucket — variar
+  shapes/valores/nombres/escenarios reales (`05_build_dataset.py` variará aún más para
+  llegar al volumen final; los seeds deben ser ya diversos, no clones).
+
+## Prohibicion absoluta
+
+- **La skill `spark-ssh` esta held-out**: cero menciones, cero ejemplos que la nombren o
+  la usen, en NINGUN bucket. `05_build_dataset.py` va a hacer un `assert` de esto sobre
+  todos los seeds combinados — si tu bucket la menciona, el build fallara.
+
+## Fuentes de verdad (leer antes de escribir, no inventar reglas)
+
+- `data/schemas/*.json` — definiciones reales de tools (154 combinadas).
+- `data/schemas/PENPOT_DEPLOYMENT_NOTES.md` — reglas de gating de Penpot (`import_image`
+  ausente, `export_shape` sin `filePath`).
+- `data/raw/sanitized/skills/*/SKILL.md` — 5 skills reales, ya sanitizadas (usar esta
+  copia, no la original de `~/.claude/skills/`).
+- `data/raw/sanitized/agents/*.md` — 7 agentes reales, ya sanitizados.
+- `data/raw/sanitized/plans/*.md` — 66 planes reales, ya sanitizados (útil para estilo de
+  reportes, ejemplos de tablas Docmost, incidentes reales para el bucket de errores).
+
+## Ejemplo completo (Docmost, formato de tabla GFM correcto)
+
+```json
+{"messages": [{"role": "user", "content": "Actualiza la tabla de progreso de mi pagina de Docmost (pageId abc-123) con: Fase 1 completada, Fase 2 en proceso."}, {"role": "assistant", "content": "", "reasoning_content": "Necesito usar update_page con markdown de tabla GFM: encabezado, fila separadora |---|, y cada fila de datos en su propia linea real -- sin la fila separadora Docmost colapsa la tabla en un parrafo ilegible.", "tool_calls": [{"id": "call_1", "type": "function", "function": {"name": "update_page", "arguments": {"pageId": "abc-123", "content": "| Fase | Estado |\\n| --- | --- |\\n| Fase 1 | Completada |\\n| Fase 2 | En proceso |\\n"}}}]}, {"role": "tool", "tool_call_id": "call_1", "name": "update_page", "content": "{\"success\": true}"}, {"role": "assistant", "content": "Listo, actualice la tabla de progreso: Fase 1 completada, Fase 2 en proceso.", "reasoning_content": "La tool confirmo exito, informo al usuario en una linea."}], "tools": [{"name": "update_page", "description": "Update an existing page's content or properties", "parameters": {"type": "object", "properties": {"pageId": {"type": "string"}, "content": {"type": "string"}}, "required": ["pageId", "content"]}}], "meta": {"bucket": "otros_mcps"}}
+```