---
name: write_issue_md
kind: function
lang: go
domain: infra
version: "0.1.0"
purity: impure
signature: "func WriteIssueMd(path string, iss Issue, body []byte) error"
description: "Serializa el frontmatter de un struct Issue a YAML y escribe el archivo Markdown en disco con formato ---\\nyaml---\\nbody. Preserva el body exactamente sin normalizar trailing newlines ni reordenar. Los campos de runtime (FilePath, MtimeNs, Completed) se omiten del YAML via yaml:\"-\"."
tags: [issue, writer, frontmatter, yaml, dev-ux, kanban]
uses_functions: []
uses_types: [issue_go_infra]
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["bytes", "fmt", "os", "gopkg.in/yaml.v3"]
params:
  - name: path
    desc: "Ruta de destino del archivo .md (puede ser la misma de la que se leyo para un update in-place)"
  - name: iss
    desc: "Struct Issue con el frontmatter a serializar. FilePath/MtimeNs/Completed se ignoran en el YAML de salida"
  - name: body
    desc: "Body MD tal como fue devuelto por ParseIssueMd — se escribe byte a byte sin modificar"
output: "nil en exito, error si el marshal YAML falla o el archivo no se puede escribir"
tested: true
tests:
  - "round-trip parse-write-parse preserva struct"
  - "archivo resultante empieza con ---"
  - "error en path inexistente"
test_file_path: "functions/infra/write_issue_md_test.go"
file_path: "functions/infra/write_issue_md.go"
---

## Ejemplo

```go
// Actualizar status de un issue in-place
iss, body, err := infra.ParseIssueMd("dev/issues/0130-kanban-cpp-v2.md")
if err != nil { log.Fatal(err) }

iss.Status = "in-progress"
iss.Updated = "2026-05-22"

if err := infra.WriteIssueMd("dev/issues/0130-kanban-cpp-v2.md", iss, body); err != nil {
    log.Fatal(err)
}
```

## Cuando usarla

Cuando el backend de kanban_cpp necesite actualizar el frontmatter de un issue (cambio de status, priority, tags, etc.) sin tocar el body. Siempre usar en par con `parse_issue_md_go_infra`: parse → modificar struct → write.

## Gotchas

- `yaml.Marshal` de v3 puede reordenar campos respecto al original — el orden del YAML de salida sera el orden de declaracion del struct `Issue`, no el del archivo original. Si el orden importa para diff legibilidad, documentarlo.
- El body se escribe byte a byte. Si lo modificas antes de pasar, lo que escribes es lo que queda.
- No hace backup previo. En sistemas con watcher activo, el write dispara un evento `write` en `watch_dir_fsnotify_go_infra` — el backend debe ignorar sus propios writes para no entrar en loop.