recall/mvp_recall.md

MVP — Gestor de conocimiento personal práctico

Documento de ejecución pensado para usar directamente con Claude Code.

---

1. Objetivo del MVP

Construir una aplicación web local-first para gestión de conocimiento personal enfocada en captura rápida, relación automática y recuperación útil.

No es una app de notas genérica. El MVP debe resolver bien estos casos:

• guardar comandos frecuentes
• guardar snippets de código
• registrar decisiones técnicas
• guardar recetas
• guardar trámites o procedimientos
• mantener inventario doméstico simple

La propuesta de valor del MVP es:

1. Guardar info rápido con fricción mínima.
2. Relacionarla sola usando metadatos, enlaces sugeridos y contenido similar.
3. Devolverla cuando importa mediante búsqueda potente y vistas útiles.

---

2. Principios del producto

2.1 Principios funcionales

• Crear una nota debe tomar menos de 10 segundos.
• La búsqueda debe encontrar contenido por título, texto, tags y tipo.
• La app debe sugerir relaciones sin exigir organización manual compleja.
• El sistema debe ser útil desde el día 1 con pocas notas.
• Debe funcionar bien para conocimiento práctico, no solo escritura larga.

2.2 Principios técnicos

• Local-first: los datos viven primero en el dispositivo.
• Simple de desplegar y mantener.
• Escalable por capas: empezar pequeño sin bloquear futuras mejoras.
• Estructura tipada: tipos de contenido claros.
• Extensible para futuro tagging semántico, embeddings y sincronización.

---

3. Alcance del MVP

3.1 Incluye

Captura

• Crear nota rápida desde un input o modal.
• Campos mínimos:
  • título
  • contenido
  • tipo
  • tags manuales opcionales
• Crear desde plantillas simples según tipo.

Tipos de nota del MVP

• command
• snippet
• decision
• recipe
• procedure
• inventory
• note (genérico)

Organización automática

• Extracción automática de:
  • fecha de creación
  • fecha de actualización
  • tipo
  • tags sugeridos por heurística simple
• Detección de notas relacionadas por:
  • coincidencia de tags
  • similitud de título
  • palabras clave compartidas
  • mismo tipo

Recuperación

• Búsqueda full-text.
• Filtros por tipo y tags.
• Vista de resultados ordenada por relevancia simple.
• Vista de “relacionadas” dentro de cada nota.
• Vista de “recientes”.

Edición

• Editar nota existente.
• Eliminar nota.
• Marcar favorita.
• Pin opcional para destacar notas críticas.

Persistencia

• Base local con SQLite.
• Exportar/importar JSON.

---

3.2 No incluye en el MVP

• colaboración multiusuario
• sincronización en la nube
• permisos y autenticación compleja
• edición en tiempo real
• embeddings/vector DB en producción
• OCR
• app móvil nativa
• plugins
• automatizaciones complejas
• parser avanzado de documentos adjuntos

---

4. Stack sugerido

Frontend

• Next.js 15 con App Router
• TypeScript
• Tailwind CSS
• shadcn/ui para componentes

Backend

• API routes / server actions de Next.js
• Prisma como ORM
• SQLite para MVP

Búsqueda

• inicialmente con consultas SQL + normalización simple
• opcional: SQLite FTS si da tiempo

Validación

• Zod

Estado

• React server components + estado local mínimo
• si hace falta: Zustand muy limitado

Testing

• Vitest para lógica
• Playwright para flujo principal si alcanza

Motivo de esta elección

Este stack permite:

• iterar rápido
• mantener una sola codebase
• ejecutar localmente fácil
• migrar luego a Postgres sin rehacer todo

---

5. Arquitectura funcional

5.1 Entidades principales

Note

Campos sugeridos:

• id
• title
• content
• type
• createdAt
• updatedAt
• isFavorite
• isPinned

Tag

• id
• name

NoteTag

• noteId
• tagId

RelatedNote

• id
• sourceNoteId
• targetNoteId
• score
• reason

Opcional en MVP si se prefiere calcular en runtime en vez de persistir.

---

5.2 Modelo de datos recomendado

model Note {
  id         String    @id @default(cuid())
  title      String
  content    String
  type       NoteType  @default(note)
  isFavorite Boolean   @default(false)
  isPinned   Boolean   @default(false)
  createdAt  DateTime  @default(now())
  updatedAt  DateTime  @updatedAt
  tags       NoteTag[]
}

model Tag {
  id    String    @id @default(cuid())
  name  String    @unique
  notes NoteTag[]
}

model NoteTag {
  noteId String
  tagId  String
  note   Note @relation(fields: [noteId], references: [id], onDelete: Cascade)
  tag    Tag  @relation(fields: [tagId], references: [id], onDelete: Cascade)

  @@id([noteId, tagId])
}

enum NoteType {
  command
  snippet
  decision
  recipe
  procedure
  inventory
  note
}

---

6. UX mínima del MVP

6.1 Pantallas

Home / Dashboard

Debe mostrar:

• barra de búsqueda principal
• botón “Nueva nota”
• sección de notas recientes
• sección de favoritas o pineadas
• filtros rápidos por tipo

Lista de notas

• búsqueda
• filtros por tipo
• filtros por tags
• cards compactas con:
  • título
  • tipo
  • preview corta
  • tags
  • fecha de actualización

Detalle de nota

• título
• tipo
• contenido
• tags
• acciones: editar, borrar, favorita, pin
• bloque “Notas relacionadas”

Crear/editar nota

• formulario simple
• selector de tipo
• área de contenido grande
• campo de tags opcional
• templates por tipo

---

6.2 Flujo ideal

1. Usuario abre app.
2. Escribe una nota nueva en segundos.
3. La nota se guarda localmente.
4. El sistema sugiere tags y notas relacionadas.
5. Días después el usuario la encuentra por búsqueda, filtro o relación.

---

7. Lógica de negocio del MVP

7.1 Reglas de creación

Al crear una nota:

• validar que título y contenido no estén vacíos
• normalizar espacios
• guardar tipo
• parsear tags manuales si existen
• generar tags sugeridos por heurística opcional

7.2 Heurísticas de tags sugeridos

Heurística simple inicial:

• extraer palabras frecuentes relevantes del título
• detectar bloques de código para sugerir code, bash, sql, etc.
• detectar patrones:
  • receta → cocina
  • decisión → arquitectura, backend, etc. según keywords
  • inventario → hogar

No hace falta IA real en MVP. Debe ser determinístico y simple.

7.3 Cálculo de relacionadas

Implementación simple:

• +3 puntos si comparten tipo
• +2 por cada tag compartido
• +1 por palabra relevante compartida en título
• +1 si una keyword del contenido aparece en ambas

Mostrar top 5 relacionadas con score > umbral.

Se puede calcular:

• on-demand en el detalle de la nota, o
• al guardar/editar la nota

Para el MVP, on-demand es suficiente.

7.4 Búsqueda

Primera versión:

• buscar en title
• buscar en content
• buscar en nombres de tags
• permitir filtro por type

Orden sugerido:

1. coincidencia en título
2. coincidencia en tags
3. coincidencia en contenido
4. updatedAt desc

---

8. Templates por tipo

command

Campos base:

• título
• comando
• explicación
• contexto de uso

Template de contenido sugerido:

## Comando

## Qué hace

## Cuándo usarlo

## Ejemplo

snippet

## Snippet

## Lenguaje

## Qué resuelve

## Notas

decision

## Contexto

## Decisión

## Alternativas consideradas

## Consecuencias

recipe

## Ingredientes

## Pasos

## Tiempo

## Notas

procedure

## Objetivo

## Pasos

## Requisitos

## Problemas comunes

inventory

## Item

## Cantidad

## Ubicación

## Notas

---

9. Estructura de carpetas sugerida

src/
  app/
    page.tsx
    notes/
      page.tsx
      [id]/page.tsx
    new/page.tsx
    edit/[id]/page.tsx
    api/
      notes/route.ts
      notes/[id]/route.ts
      search/route.ts
  components/
    note-form.tsx
    note-card.tsx
    note-list.tsx
    search-bar.tsx
    related-notes.tsx
    filters.tsx
    dashboard.tsx
  lib/
    prisma.ts
    db.ts
    search.ts
    related.ts
    tags.ts
    templates.ts
    validators.ts
  types/
    note.ts
prisma/
  schema.prisma

---

10. API / acciones mínimas

CRUD de notas

• GET /api/notes
• POST /api/notes
• GET /api/notes/:id
• PUT /api/notes/:id
• DELETE /api/notes/:id

búsqueda

• GET /api/search?q=...&type=...&tag=...

export/import

• GET /api/export
• POST /api/import

---

11. Historias de usuario principales

HU1 — Crear nota rápida

Como usuario, quiero crear una nota en pocos segundos, para no perder información útil.

Criterios de aceptación:

• puedo crear una nota con título, contenido y tipo
• queda persistida localmente
• aparece en recientes inmediatamente

HU2 — Buscar conocimiento guardado

Como usuario, quiero encontrar una nota por texto libre, para recuperar información cuando la necesito.

Criterios:

• la búsqueda encuentra coincidencias en título y contenido
• puedo filtrar por tipo
• resultados aparecen rápido

HU3 — Ver contenido relacionado

Como usuario, quiero que el sistema me muestre notas relacionadas, para redescubrir información útil.

Criterios:

• cada nota muestra hasta 5 relacionadas
• la relación se basa en reglas simples entendibles

HU4 — Usar plantillas

Como usuario, quiero crear notas con estructura base según el tipo, para capturar mejor cada caso.

Criterios:

• al elegir un tipo puedo cargar un template sugerido
• puedo editar el template libremente

HU5 — Exportar datos

Como usuario, quiero exportar mis datos, para no quedar atado a la app.

Criterios:

• exporta a JSON válido
• puedo reimportar ese JSON

---

12. Roadmap de implementación del MVP

Fase 1 — Base funcional

Objetivo: tener CRUD y persistencia.

Entregables:

• setup Next.js + Tailwind + Prisma + SQLite
• schema Prisma
• migraciones
• CRUD básico de notas
• listado y detalle
• formulario crear/editar

Fase 2 — Búsqueda y filtros

Objetivo: recuperar bien.

Entregables:

• search por título/contenido
• filtros por tipo
• filtros por tags
• home con recientes y favoritas

Fase 3 — Relación automática

Objetivo: conectar conocimiento.

Entregables:

• heurística de tags sugeridos
• cálculo de relacionadas
• UI de relacionadas en detalle

Fase 4 — Pulido MVP

Objetivo: dejarlo presentable y usable.

Entregables:

• templates por tipo
• export/import JSON
• validaciones
• estados vacíos
• seed de ejemplo

---

13. Definición de terminado

El MVP está listo cuando:

• se puede crear, editar y borrar notas
• las notas se persisten en SQLite
• se puede buscar por texto
• se puede filtrar por tipo y tags
• cada nota muestra relacionadas
• existen templates por tipo
• existe export/import JSON
• la UI es suficientemente clara para uso diario local

---

14. Riesgos y cómo reducirlos

Riesgo 1: demasiada ambición

Mitigación:

• no agregar sync ni IA real al MVP
• priorizar velocidad de uso y recuperación

Riesgo 2: búsqueda pobre

Mitigación:

• priorizar calidad de búsqueda antes de features cosméticas
• evaluar SQLite FTS si la búsqueda simple queda corta

Riesgo 3: relaciones poco útiles

Mitigación:

• mantener heurísticas transparentes
• mostrar razones simples del match en una versión futura

Riesgo 4: modelo demasiado genérico

Mitigación:

• usar tipos concretos desde el inicio
• mantener note genérico solo como fallback

---

15. Mejoras post-MVP

• sincronización entre dispositivos
• embeddings para similitud semántica real
• parser de comandos/snippets automático
• extensión de navegador para guardar rápido
• captura por share sheet móvil
• recordatorios contextuales
• grafos de relación
• OCR y adjuntos
• versionado de notas
• vistas especializadas por tipo

---

16. Prompt maestro para ejecutar en Claude Code

Usar este prompt como instrucción principal:

Quiero que construyas un MVP funcional de una aplicación llamada “Gestor de conocimiento personal práctico”.

Objetivo del producto:
- guardar info rápido
- relacionarla sola
- devolverla cuando importa

Casos de uso principales:
- comandos
- snippets
- decisiones técnicas
- recetas
- trámites/procedimientos
- inventario doméstico

Stack requerido:
- Next.js 15 con App Router
- TypeScript
- Tailwind CSS
- shadcn/ui
- Prisma
- SQLite
- Zod

Requisitos funcionales del MVP:
1. CRUD completo de notas.
2. Tipos de nota: command, snippet, decision, recipe, procedure, inventory, note.
3. Formulario de creación/edición con título, contenido, tipo y tags opcionales.
4. Dashboard con búsqueda, recientes y favoritas/pineadas.
5. Lista de notas con filtros por tipo y tags.
6. Búsqueda por título, contenido y tags.
7. Página de detalle con notas relacionadas.
8. Templates simples por tipo.
9. Exportar e importar JSON.
10. Persistencia local usando SQLite.

Reglas de relacionadas:
- +3 si comparten tipo
- +2 por cada tag compartido
- +1 por palabra relevante compartida en el título
- +1 por keyword compartida en el contenido
- mostrar top 5 con score suficiente

Restricciones:
- No implementar autenticación.
- No implementar sync cloud.
- No implementar IA compleja ni vector DB.
- Mantener el código limpio, modular y listo para evolucionar.

Quiero que generes:
1. La estructura inicial del proyecto.
2. El schema de Prisma.
3. Los componentes principales.
4. Las rutas/páginas necesarias.
5. Las utilidades para búsqueda, tags y relacionadas.
6. Un seed de datos de ejemplo.
7. Instrucciones claras para correr el proyecto.

Además:
- usa buenas prácticas
- separa responsabilidades
- evita sobreingeniería
- deja comentarios donde aporten claridad
- entrega una primera versión funcional de punta a punta

---

17. Prompt por etapas para Claude Code

Etapa 1 — Setup base

Crea el proyecto base con Next.js 15, TypeScript, Tailwind, Prisma y SQLite. Configura la estructura de carpetas, instala dependencias, crea el schema inicial de Prisma para Note, Tag y NoteTag, genera migración y deja una app corriendo con una página home básica.

Etapa 2 — CRUD

Implementa el CRUD completo de notas. Debe existir listado, detalle, creación, edición y borrado. Cada nota debe tener title, content, type, tags opcionales, isFavorite e isPinned. Usa validación con Zod.

Etapa 3 — Búsqueda y filtros

Implementa búsqueda por texto sobre título, contenido y tags. Agrega filtros por tipo y tags. Crea una home con notas recientes, favoritas y acceso rápido a crear nota.

Etapa 4 — Relacionadas

Implementa la lógica de notas relacionadas usando reglas heurísticas simples. Muestra hasta 5 notas relacionadas en la vista de detalle.

Etapa 5 — Templates y export/import

Agrega templates por tipo de nota y funciones para exportar e importar datos en JSON. Incluye manejo básico de errores y estados vacíos.

---

18. Checklist de validación manual

• La app inicia sin errores.
• Se puede crear una nota.
• Se puede editar una nota.
• Se puede eliminar una nota.
• La búsqueda encuentra texto por título.
• La búsqueda encuentra texto por contenido.
• Se puede filtrar por tipo.
• Las tags se guardan y se pueden usar como filtro.
• El detalle muestra relacionadas.
• Se puede exportar JSON.
• Se puede importar JSON.
• Hay seed de ejemplo útil para probar.

---

19. Criterio de éxito del MVP

El MVP será exitoso si una persona puede usarlo durante una semana para guardar y recuperar conocimiento práctico sin sentir que necesita otra herramienta para:

• recordar comandos
• reutilizar snippets
• revisar decisiones
• seguir procedimientos
• consultar inventario o recetas

---

20. Recomendación final

Para este MVP conviene optimizar en este orden:

1. velocidad de captura
2. calidad de búsqueda
3. utilidad de relacionadas
4. claridad visual
5. exportabilidad

No priorizar IA antes de demostrar que la base manual + heurística ya resuelve valor real.