recall/backlog/recall-mvp3-tickets-claude-code.md

# Recall — Tickets técnicos MVP-3 para Claude Code

## Objetivo general
Convertir Recall en una herramienta indispensable de uso diario, enfocada en:
- recuperación pasiva
- ranking basado en uso real
- sugerencias automáticas
- mapa de conocimiento simple
- reducción adicional de fricción en captura

---

# EPIC 1 — Dashboard y uso diario

## [P1] Ticket 01 — Rediseñar dashboard para valor inmediato

**Objetivo**  
Hacer que la pantalla inicial devuelva valor sin necesidad de buscar.

**Contexto**  
Recall ya soporta búsqueda avanzada, quick add, backlinks, notas relacionadas, tags y UX especializada por tipo. El siguiente paso es que el home priorice descubrimiento y reutilización.

**Alcance**
- Reemplazar dashboard actual por bloques orientados a uso:
  - notas recientes
  - notas más usadas
  - comandos recientes
  - snippets recientes
  - sugerencias relacionadas a la actividad reciente
- Crear endpoint o función de agregación para dashboard
- Ordenar visualmente por relevancia, no solo por fecha

**No incluye**
- métricas históricas avanzadas
- personalización por usuario

**Criterios de aceptación**
- Al abrir `/`, se ven al menos 4 bloques útiles
- “Más usadas” no depende solo de `updatedAt`
- Los bloques no rompen con base vacía
- El dashboard responde correctamente con 0, pocas o muchas notas

**Archivos sugeridos**
- `src/app/page.tsx`
- `src/components/dashboard.tsx`
- `src/lib/dashboard.ts`
- `src/app/api/dashboard/route.ts` (opcional)

**Notas técnicas**
- Reutilizar scoring y modelos existentes
- Mantener SSR o server components donde tenga sentido

---

## [P1] Ticket 02 — Registrar eventos de uso de notas

**Objetivo**  
Capturar señales reales de uso para mejorar ranking y sugerencias.

**Alcance**
- Crear modelo de uso o contador agregado
- Registrar eventos mínimos:
  - apertura de nota
  - copia de comando
  - copia de snippet
  - uso desde quick add relacionado
- Exponer utilidades para incrementar métricas

**No incluye**
- tracking externo
- analytics de terceros

**Criterios de aceptación**
- Abrir una nota incrementa su contador de uso
- Copiar contenido especializado suma señal adicional
- La captura falla de forma segura sin romper la UI
- Se puede consultar el uso agregado por nota

**Archivos sugeridos**
- `prisma/schema.prisma`
- `src/lib/usage.ts`
- `src/app/api/notes/[id]/usage/route.ts`
- `src/components/note-card.tsx`
- `src/components/markdown-content.tsx`

**Notas técnicas**
- Preferir modelo simple:
  - `NoteUsage` por evento o
  - campos agregados en `Note`
- Si eliges eventos, agregar tarea/helper de agregación futura

---

## [P1] Ticket 03 — Mostrar “según tu actividad reciente”

**Objetivo**  
Crear recuperación pasiva basada en uso reciente.

**Alcance**
- Detectar últimas notas abiertas/usadas
- Sugerir notas relacionadas en dashboard
- Crear bloque “Según tu actividad reciente”

**Criterios de aceptación**
- Si hay actividad reciente, aparecen sugerencias relevantes
- Si no hay actividad, el bloque se oculta o usa fallback
- El bloque muestra por qué se recomienda una nota

**Archivos sugeridos**
- `src/lib/dashboard.ts`
- `src/components/dashboard.tsx`
- `src/lib/related.ts`
- `src/lib/usage.ts`

---

# EPIC 2 — Ranking inteligente y recuperación pasiva

## [P1] Ticket 04 — Extender scoring con señales de uso real

**Objetivo**  
Mejorar la relevancia de búsqueda y recomendaciones con comportamiento real.

**Alcance**
- Extender `search.ts` y/o `related.ts` para incluir:
  - cantidad de aperturas
  - copias
  - recencia de uso
  - frecuencia de uso
- Ajustar pesos de scoring

**No incluye**
- machine learning
- embeddings

**Criterios de aceptación**
- Una nota muy usada sube en empates razonables
- El ranking sigue priorizando match textual fuerte
- El score es explicable y testeable

**Archivos sugeridos**
- `src/lib/search.ts`
- `src/lib/related.ts`
- `src/lib/usage.ts`
- `__tests__/search.test.ts`
- `__tests__/related.test.ts`

**Notas técnicas**
- No permitir que uso alto eclipse resultados textualmente irrelevantes
- Mantener scoring determinístico

---

## [P1] Ticket 05 — Crear recomendaciones pasivas en detalle de nota

**Objetivo**  
Que una nota devuelva otras útiles sin necesidad de nueva búsqueda.

**Alcance**
- En vista de detalle agregar bloque:
  - “También podrías necesitar”
- Basar sugerencias en:
  - backlinks
  - related score
  - uso conjunto
  - tags compartidos

**Criterios de aceptación**
- El bloque aparece en detalle de nota
- Muestra entre 3 y 6 sugerencias
- Muestra razón resumida de recomendación
- Excluye nota actual y duplicados

**Archivos sugeridos**
- `src/app/notes/[id]/page.tsx`
- `src/components/related-notes.tsx`
- `src/lib/recommendations.ts`

---

## [P2] Ticket 06 — Registrar co-uso entre notas

**Objetivo**  
Detectar notas que suelen usarse juntas.

**Alcance**
- Al abrir una nota, registrar relación con notas abiertas recientemente
- Generar señal de co-uso
- Exponer helper para recomendar “suelen usarse juntas”

**Criterios de aceptación**
- El sistema puede devolver notas co-usadas
- No hay duplicados ni relaciones simétricas inconsistentes
- La implementación escala razonablemente para dataset pequeño/medio

**Archivos sugeridos**
- `prisma/schema.prisma`
- `src/lib/co-usage.ts`
- `src/lib/recommendations.ts`

---

# EPIC 3 — Sugerencias automáticas y enriquecimiento

## [P1] Ticket 07 — Sugerir tags automáticamente al escribir

**Objetivo**  
Reducir esfuerzo manual en clasificación.

**Alcance**
- Analizar título y contenido del formulario
- Sugerir tags existentes según:
  - coincidencias de términos
  - frecuencia histórica
  - tipo de nota
- Mostrar sugerencias no invasivas

**Criterios de aceptación**
- Al escribir contenido aparecen sugerencias útiles
- El usuario puede aceptar o ignorar sugerencias
- No se agregan tags automáticamente sin acción del usuario
- Funciona con debounce

**Archivos sugeridos**
- `src/app/api/tags/suggest/route.ts`
- `src/lib/tags.ts`
- `src/components/note-form.tsx`

**Notas técnicas**
- Priorizar tags existentes para evitar proliferación innecesaria

---

## [P2] Ticket 08 — Sugerir tipo de nota automáticamente

**Objetivo**  
Acelerar creación cuando el usuario pega contenido ambiguo.

**Alcance**
- Detectar patrones de contenido para sugerir tipo:
  - bloque de código → `snippet`
  - comando shell → `command`
  - lista de pasos → `procedure`
  - ingredientes/pasos → `recipe`
  - contexto/decisión → `decision`
- Mostrar recomendación editable

**Criterios de aceptación**
- El formulario propone un tipo probable
- El usuario puede mantener o cambiar el tipo
- No sobrescribe tipo si el usuario ya eligió uno manualmente

**Archivos sugeridos**
- `src/lib/type-inference.ts`
- `src/components/note-form.tsx`
- `__tests__/type-inference.test.ts`

---

## [P2] Ticket 09 — Sugerir links internos mientras se escribe

**Objetivo**  
Fortalecer la red de conocimiento sin depender de memoria del usuario.

**Alcance**
- Analizar contenido y detectar posibles referencias a notas existentes
- Sugerir convertir términos en `[[nota]]`
- Permitir inserción con un click

**Criterios de aceptación**
- El sistema detecta coincidencias plausibles con títulos existentes
- El usuario puede insertar el link sugerido
- No genera links automáticos sin confirmación

**Archivos sugeridos**
- `src/lib/backlinks.ts`
- `src/lib/link-suggestions.ts`
- `src/components/note-form.tsx`

---

# EPIC 4 — Mapa de conocimiento simple

## [P1] Ticket 10 — Crear panel “Conectado con”

**Objetivo**  
Dar una vista de contexto inmediata sin construir un grafo complejo.

**Alcance**
- En detalle de nota, agregar panel lateral o bloque:
  - backlinks
  - links salientes
  - relacionadas
  - co-usadas
- Agrupar visualmente cada tipo de relación

**Criterios de aceptación**
- La nota muestra claramente su red local
- Se distinguen tipos de conexión
- Los enlaces navegan correctamente
- Con 0 conexiones el bloque no se rompe

**Archivos sugeridos**
- `src/app/notes/[id]/page.tsx`
- `src/components/note-connections.tsx`
- `src/lib/backlinks.ts`
- `src/lib/related.ts`
- `src/lib/recommendations.ts`

---

## [P2] Ticket 11 — Identificar notas centrales

**Objetivo**  
Detectar nodos importantes del conocimiento personal.

**Alcance**
- Calcular una métrica simple de centralidad usando:
  - backlinks
  - links salientes
  - uso
  - co-uso
- Mostrar bloque “Notas centrales” en dashboard

**Criterios de aceptación**
- El dashboard muestra las notas más centrales
- La métrica está documentada y es reproducible
- Los resultados cambian al aumentar conexiones reales

**Archivos sugeridos**
- `src/lib/centrality.ts`
- `src/lib/dashboard.ts`
- `src/components/dashboard.tsx`
- `__tests__/centrality.test.ts`

---

# EPIC 5 — Captura aún más rápida

## [P1] Ticket 12 — Mejorar Quick Add para texto multilinea

**Objetivo**  
Permitir capturar cosas más complejas sin abrir el formulario completo.

**Alcance**
- Soportar textarea o modo expandido en `quick-add`
- Mantener parseo de prefijos y tags
- Permitir pegar bloques de texto/código/listas

**Criterios de aceptación**
- Se puede guardar una nota multilinea desde quick add
- El parser mantiene tags y tipo correctamente
- No rompe el flujo actual de una sola línea

**Archivos sugeridos**
- `src/components/quick-add.tsx`
- `src/lib/quick-add.ts`
- `src/app/api/notes/quick/route.ts`

---

## [P2] Ticket 13 — Pegado inteligente en Quick Add y formulario

**Objetivo**  
Inferir estructura útil cuando el usuario pega contenido.

**Alcance**
- Detectar si el pegado parece:
  - comando
  - snippet
  - checklist
  - markdown
- Preformatear el contenido para mejor guardado
- Ofrecer sugerencia de tipo o plantilla

**Criterios de aceptación**
- Pegar código sugiere `snippet`
- Pegar checklist preserva formato
- Pegar comando corto no destruye el flujo rápido

**Archivos sugeridos**
- `src/lib/paste-analysis.ts`
- `src/components/quick-add.tsx`
- `src/components/note-form.tsx`

---

# EPIC 6 — Métricas y observabilidad de producto

## [P2] Ticket 14 — Crear métricas internas simples

**Objetivo**  
Medir qué partes del producto generan valor real.

**Alcance**
- Crear panel o función para obtener:
  - notas más abiertas
  - tipos más usados
  - tags más usados
  - quick add vs formulario
- Exponer datos al dashboard o settings

**Criterios de aceptación**
- Las métricas se calculan sin servicios externos
- Se pueden consultar desde UI
- No impactan negativamente el rendimiento percibido

**Archivos sugeridos**
- `src/lib/metrics.ts`
- `src/app/settings/page.tsx` o `src/app/page.tsx`
- `src/app/api/metrics/route.ts`

---

## [P2] Ticket 15 — Instrumentar origen de creación de nota

**Objetivo**  
Saber qué flujo usan más los usuarios.

**Alcance**
- Registrar si la nota se creó desde:
  - quick add
  - formulario completo
  - importación
- Guardar origen de creación
- Exponerlo en métricas

**Criterios de aceptación**
- Cada nota nueva guarda su origen
- Las métricas muestran distribución por origen
- No rompe notas existentes

**Archivos sugeridos**
- `prisma/schema.prisma`
- `src/app/api/notes/route.ts`
- `src/app/api/notes/quick/route.ts`
- `src/app/api/export-import/route.ts`
- `src/lib/metrics.ts`

---

# EPIC 7 — Calidad y estabilidad

## [P1] Ticket 16 — Tests unitarios para ranking y recomendaciones MVP-3

**Objetivo**  
Proteger la lógica nueva antes de seguir iterando.

**Alcance**
- Tests para:
  - `usage.ts`
  - `dashboard.ts`
  - `recommendations.ts`
  - `type-inference.ts`
  - `centrality.ts`

**Criterios de aceptación**
- Casos felices y bordes cubiertos
- Tests reproducibles con datos determinísticos
- Los pesos de scoring quedan documentados por test

---

## [P1] Ticket 17 — Tests de integración para dashboard y usage tracking

**Objetivo**  
Validar flujos reales del MVP-3.

**Alcance**
- Probar:
  - apertura/uso de nota
  - dashboard enriquecido
  - recomendaciones
  - métricas base

**Criterios de aceptación**
- Existen seeds o fixtures simples
- Los endpoints responden con estructura consistente
- No hay regresiones en APIs existentes

---

## [P2] Ticket 18 — Feature flags internas para MVP-3

**Objetivo**  
Introducir features progresivamente sin romper experiencia principal.

**Alcance**
- Crear configuración simple para activar/desactivar:
  - centralidad
  - recomendaciones pasivas
  - sugerencias de tipo
  - sugerencias de links
- Leer flags desde config local o env

**Criterios de aceptación**
- Cada feature nueva puede apagarse sin romper la app
- Los componentes respetan flags en servidor y cliente

**Archivos sugeridos**
- `src/lib/features.ts`
- `src/app/layout.tsx`
- componentes afectados

---

# Orden recomendado de implementación

## Sprint 1
- Ticket 02 — Registrar eventos de uso de notas
- Ticket 04 — Extender scoring con señales de uso real
- Ticket 01 — Rediseñar dashboard para valor inmediato
- Ticket 03 — Mostrar “según tu actividad reciente”
- Ticket 16 — Tests unitarios MVP-3 base

## Sprint 2
- Ticket 05 — Recomendaciones pasivas en detalle
- Ticket 07 — Sugerir tags automáticamente
- Ticket 10 — Panel “Conectado con”
- Ticket 17 — Tests de integración

## Sprint 3
- Ticket 12 — Quick Add multilinea
- Ticket 13 — Pegado inteligente
- Ticket 08 — Sugerir tipo automáticamente
- Ticket 09 — Sugerir links internos

## Sprint 4
- Ticket 06 — Registrar co-uso
- Ticket 11 — Identificar notas centrales
- Ticket 14 — Métricas internas simples
- Ticket 15 — Origen de creación
- Ticket 18 — Feature flags internas

---

# Plantilla sugerida para cada issue en Claude Code

## Título
`[P1] Registrar eventos de uso de notas`

## Contexto
Recall ya cuenta con CRUD, búsqueda con scoring, quick add, backlinks, relaciones y tests. Ahora se necesita capturar señales reales de uso para mejorar ranking y recomendaciones.

## Objetivo
Registrar aperturas y acciones clave sobre notas para alimentar el dashboard, la recuperación pasiva y el ranking inteligente.

## Alcance
- modelo o estructura de persistencia
- utilidades de registro
- integración mínima con UI y/o endpoints
- tests asociados

## No incluye
- analytics de terceros
- tracking publicitario
- panel complejo de observabilidad

## Criterios de aceptación
- ...
- ...
- ...

## Archivos a tocar
- ...
- ...

## Notas técnicas
- mantener compatibilidad con Prisma + SQLite
- implementación segura ante fallos
- no romper experiencia actual

---

# Definición de Done

- Código implementado y tipado
- Tests pasando
- Sin regresiones en CRUD/búsqueda/quick add
- UI usable en estados vacío, normal y borde
- Lógica desacoplada en `lib/`