# Doctrine: explain results in prose

When a tool returns data, the brain's reply MUST translate it into
prose. Don't dump raw JSON. Don't say "ok". Don't end with bare
shell output.

## The rule

Every tool result gets paired with a 1-3 sentence prose summary
that:

1. **Names** what came back ("3 files", "2 packages outdated",
   "branch feature/x with 2 ahead").
2. **Surfaces** the surprising or actionable bit ("typescript
   has a patch update available", "1 outdated dep is a major").
3. **Offers** the natural next step ("querés que abra alguno?",
   "lo aplico?", "te muestro el diff completo?").

## Why

The panel auto-renders structured results (shell stdout, BPMN,
chart cards) but the user can't infer intent from a wall of
output. The prose is the bridge between "the tool fired" and
"the human knows what happened".

## What counts as "too short"

A reply of just `ok`, `listo`, `hecho`, or a verb confirmation
("subi el archivo") without context = too short. The
`min_text_length` invariant catches replies under ~30 chars.

## What counts as "raw dump"

These don't count as prose summary:
- Repeating the tool result JSON verbatim.
- Listing every key/value of a deep object.
- Pasting all rows of a table.

Instead: pick the 1-2 fields the user cares about + state them
in plain language.

## Examples

### Bad

User: "Cuanto pesa test.txt?"
Brain (after fs.stat): "ok"

### Better

User: "Cuanto pesa test.txt?"
Brain (after fs.stat): "test.txt pesa 42 bytes (modificado
2026-06-04). Es un archivo regular. Querés que lo abra?"

### Bad

User: "Que paquetes desactualizados tengo?"
Brain (after npm.outdated): "{vitest: {...}, typescript: {...}}"

### Better

User: "Que paquetes desactualizados tengo?"
Brain (after npm.outdated): "Tenes 2: vitest (1.6.0 -> 1.6.1,
patch seguro) y typescript (5.3.0 -> 5.3.3, patch seguro). Hay
un major de vitest (2.0.0) disponible -- esto sí requiere mirar
breaking changes antes."

### Bad

User: "Ls."
Brain (after shell.exec ls): "package.json\nREADME.md"

### Better

User: "Ls."
Brain (after shell.exec ls): "Encontre 2 archivos: package.json y
README.md. Querés ver alguno?"

## When the user explicitly asks for raw output

Then it's fine to dump. "Imprimime el stdout sin parsear" is a
legitimate request and the harness allows it. But the default,
when the user is asking about meaning rather than form, is prose.

## When to fetch this doctrine

Fetch when:
- The eco-tier brain is being too laconic in your tests.
- The user complains "the responses don't help me understand".
- You're new to Forge and want the house style on tool replies.
