---
id: "0104"
title: "/fix-issue type-aware dispatch (chore vs feature vs bugfix vs epic)"
status: pendiente
type: feature
domain:
  - meta
  - dev-ux
scope: registry-only
priority: alta
depends:
  - "0100"
blocks: []
related:
  - "0101"
  - "0103"
created: 2026-05-17
updated: 2026-05-17
tags: [slash-command, dispatch, type-aware]
---

# 0104 — `/fix-issue` type-aware dispatch

## Problema

Hoy `/fix-issue NNNN` arranca con el mismo flujo para CUALQUIER tipo de issue. Pero un `chore` (limpieza, migracion idempotente) no requiere el mismo ceremonial que un `feature` (TBD rama + acceptance + DoD), ni que un `bugfix` (reproduce + test que falla + fix + test verde), ni que un `epic` (planificacion de sub-issues, no codigo directo).

Resultado:
- `chore` se ejecuta con TBD branch innecesaria, ralentiza.
- `bugfix` se cierra sin test de regresion porque el flujo no lo exige.
- `epic` arranca con `/git-branch` aunque no toca codigo aun (deberia abrir sub-issues primero).
- `spike` se trata como feature, sin timebox.
- `docs` requiere ramas TBD que sobran (push directo a master segun apps_tbd.md para registry).

## Objetivo

`/fix-issue NNNN` lee el `type:` del frontmatter (issue 0100) y aplica el playbook correspondiente. Sin type valido -> error "type missing, run `/issue tag NNNN +type:<X>` first".

## Dispatch por type

### `bugfix`

1. `/git-branch issue/NNNN-<slug>`.
2. **Reproducir el bug**: pedir al usuario pasos exactos + snippet. Si no se reproduce -> abort.
3. **Escribir test que falla** ANTES del fix. Commit `test: reproduce <bug>`.
4. Implementar fix.
5. Test verde + run suite completa de la app afectada.
6. Commit `fix: <descripcion>`.
7. `/git-push` (merge --no-ff master).
8. Move a `completed/`.

### `feature`

1. `/git-branch issue/NNNN-<slug>`.
2. **Plan corto** (2-3 frases) sobre approach + DoD a marcar.
3. Implementar bloque por bloque, commits atomicos.
4. Acceptance checkboxes verdes via tests + manual user-test.
5. Si DoD pide `User-facing`: el flow asociado debe abrir la superficie usuario.
6. `/git-push`.
7. Move a `completed/`.

### `chore`

1. **NO TBD branch** (push directo a master). Si toca app -> usar TBD.
2. Si es pipeline idempotente: run `--dry-run` primero, mostrar diff, run real.
3. Backup antes de toda escritura masiva (ver 0100).
4. Commit `chore: <descripcion>`.
5. `/full-git-push`.
6. Move a `completed/`.

### `refactor`

1. `/git-branch issue/NNNN-<slug>`.
2. **Sin tests verdes pre-existentes -> abort**. Refactor sin red de seguridad es feature, no refactor.
3. Aplicar **Branch by Abstraction** (ver feature_flags.md) si cambio grande.
4. Tests siguen verdes en cada commit.
5. `/git-push`.

### `chore` + `audit`

1. Read-only fase exploratoria.
2. Output reporte (no escribir).
3. Si el reporte requiere fix -> abrir nuevo issue `bugfix` o `chore` por hallazgo.
4. Close audit issue con reporte adjunto en `## Notas`.

### `epic`

1. **NO codigo directo**. Epic es planning.
2. Listar sub-issues hijo (`NNNNa`, `NNNNb`, ...) — crearlos si no existen via `/issue create`.
3. Decidir orden de ejecucion (dependencias).
4. Status del epic = `bloqueado` mientras haya hijos abiertos.
5. Cerrar solo cuando todos los hijos esten `completado`.

### `spike`

1. `/git-branch spike/NNNN-<slug>` (no `issue/`).
2. **Timebox declarado** en frontmatter (`tags: [timebox-2h]`).
3. Output: aprendizaje en `## Notas` + nuevo issue concreto (feature/refactor) si vale la pena seguir.
4. NO commit a master. Si el spike falla -> branch deletada, issue `deferred`.

### `docs`

1. NO TBD (push directo).
2. Editar `.md` o `docs/` o reglas.
3. Si toca `.claude/rules/INDEX.md` -> verificar referencias rotas.
4. Commit `docs: <descripcion>`.

### `infra`

1. Sub-issue de un epic. `/fix-issue` redirige a guidance del epic padre.
2. Aplicar dispatch del type del padre (feature/refactor habitualmente).

### `planning`

1. NO codigo. Similar a `epic` pero scope mas pequeño (ej. propuesta de taxonomia, ADR).
2. Output: `.md` con conclusiones.

## Implementacion

Slash command `.claude/commands/fix-issue.md` actualizado:

```yaml
---
description: "Fix issue con dispatch por type (bugfix/feature/chore/refactor/epic/spike/docs/infra/planning)"
allowed-tools: [Bash, Read, Edit, Write, Glob, Grep, Agent]
---

# /fix-issue NNNN

1. Lee `dev/issues/NNNN-*.md` (parsea frontmatter YAML).
2. Lee `type:` del frontmatter.
3. Despacha al playbook correspondiente (ver dev/issues/0104-*.md).
4. Si type missing/invalido -> error con sugerencia.
```

Playbooks se materializan como sub-archivos en `dev/playbooks/<type>.md` (lectura on-demand). Cada uno con steps numerados + checklist DoD.

## Acceptance

- [ ] `.claude/commands/fix-issue.md` lee `type:` y dispacha.
- [ ] `dev/playbooks/{bugfix,feature,chore,refactor,epic,spike,docs,infra,planning}.md` existen.
- [ ] `/fix-issue NNNN` sin `type:` valido -> error claro + sugerencia.
- [ ] Documentacion en `.claude/rules/` referencia los playbooks.
- [ ] Smoke test: `/fix-issue 0099` (type=app) elige el playbook adecuado (mapea app -> feature playbook por defecto).

## Definition of Done

### Generico

- [ ] **Repetibilidad**: misma issue type produce mismo playbook 100x.
- [ ] **Observabilidad**: log "dispatch: type=feature" antes de arrancar.
- [ ] **Error-path**: type invalido -> error con sugerencia "did you mean ...?".
- [ ] **Idempotencia**: si la rama ya existe, reanudar (no abortar).
- [ ] **Secrets**: N/A.
- [ ] **Docs**: cada playbook tiene ejemplo + gotchas.
- [ ] **Registry-first**: playbooks reusan funciones del registry (git_branch, run_tests, etc.).
- [ ] **INDEX + status**: issue cerrado.

### User-facing

- [ ] **User-facing**: usuario teclea `/fix-issue 0099` y ve el playbook elegido como primera linea: `[dispatch] type=app -> playbook=feature (TBD branch + acceptance + DoD)`.
- [ ] **User-facing repeat**: cada issue futuro entra al playbook correcto automatico, sin que el usuario tenga que pensar.
- [ ] **User-facing onboarding**: parrafo en `dev/playbooks/README.md` explica que es cada playbook.
- [ ] **User-facing latencia**: dispatch decision <100ms.

## Notas

(rellenas tras correr)
