CommunityRedacción y edicióngithub.com

YujunZhou/tellonce

Habilidad de cumplimiento normativo dentro de la sesión para Claude Code (paper Sec 6 dogfood). Umbral adaptativo por usuario + instalación/desinstalación probada contra caos.

¿Qué es tellonce?

Tellonce es una habilidad para Claude Code que implementa un sistema de cumplimiento normativo dentro de la sesión, diseñado para ayudar al agente a recordar y respetar las preferencias del usuario de manera progresiva. Por defecto, opera en modo solo observación, registrando señales de preferencia sin bloquear la sesión ni enviar datos a un LLM externo. Cuando se activa explícitamente (con variables de entorno como `PT_ENFORCE=1` y `PT_SHADOW=1`), puede aplicar reglas de bloqueo deterministas y un juez LLM sombra para puntuación semántica. La habilidad instala tres capas de infraestructura: inyección de reglas de memoria, un registro de cumplimiento solo para auditoría, y un mecanismo de puerta que verifica que se haya realizado un escaneo de preferencias en cada turno. El objetivo es evitar que el agente olvide preferencias importantes, reduciendo la fricción del usuario en sesiones múltiples mediante la detección semántica de señales y una gestión inteligente del coste de falsos positivos frente a omisiones. Está probado contra caos en instalación, verificación y desinstalación.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add YujunZhou/tellonce

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace tellonce?

Modos de Ejecución y Valores Predeterminados (Lanzamiento Público)

Por defecto = modo observación (solo observar): por defecto, esta habilidad solo hace "escanear preferencias → registrar → informar al usuario". Nunca bloquea la sesión y nunca llama a un LLM. Un nuevo usuario que acaba de instalarlo no será interceptado por ninguna regla estricta, ni se enviará el contenido de su conversación a un modelo de terceros.

  • Aplicación de bloqueo estricto (bloqueo determinista / compuerta pendiente / compuerta de registro de observación) está desactivada por defecto; debes establecer explícitamente PT_ENFORCE=1 para habilitarla.
  • El juez LLM sombra (enviar la conversación a un modelo externo para puntuación semántica) está desactivado por defecto; debes establecer explícitamente PT_SHADOW=1 para habilitarlo. Nota de privacidad: una vez habilitado, cada turno envía "el último mensaje del usuario + la respuesta del asistente" (con claves API/contraseñas, etc., redactadas) a ese modelo.
  • seed_memory/ se envía intencionalmente vacío (solo un README como explicación): no hay reglas de preferencia preinstaladas; tus reglas se acumulan una por una en uso mediante la Función de Puerta.

Cambiar modos (variables de entorno; no establecer ninguna = el modo seguro por defecto de solo observación):

PT_ENFORCE=1   # habilitar intercepción estricta
PT_SHADOW=1    # habilitar el juez IA (modo sombra)

Las secciones de Infraestructura / Puerta a continuación describen el comportamiento después de habilitar el modo de aplicación. En el modo de observación predeterminado, estas puertas solo registran y no bloquean.

Infraestructura

Esta habilidad es más que la Ley de Hierro + Función de Puerta. Instala 3 capas de infraestructura que se ejecutan como enganches automáticos, teniendo efecto sin una invocación explícita de la Habilidad.

Nota sobre marcadores de posición de ruta: en el texto a continuación, <skill_dir> por defecto es ~/.claude/skills/tellonce/, <project_root> es la raíz del proyecto actual, y <state_dir> es <project_root>/.claude/tellonce-state/. Todas las rutas se resuelven en tiempo de ejecución por lib/path_config.py (una degradación de tres niveles: env > ~/.tellonce.config.json > detección automática); SKILL.md no codifica rutas absolutas para evitar contaminar la salida de Claude.

Inyección de reglas (índice completo progresivo — predeterminado)

Cada vez que el usuario envía un mensaje, <skill_dir>/hooks/memory-retrieve-inject.sh inyecta un índice de una línea de las reglas guardadas en mi directorio de memoria como additionalContext, y yo juzgo cuáles aplicar. Si la biblioteca excede el límite por turno (predeterminado 50 — progressive_max en ~/.tellonce.config.json o B5_PROGRESSIVE_MAX, 0 = sin límite), las reglas de nivel 1 se fijan cuando caben dentro del límite (cuando el nivel 1 solo lo desborda, toda la biblioteca rota en su lugar), las reglas restantes rotan a lo largo de los turnos, y el bloque indica cuántas del total se muestran. Este es el backend progressive predeterminado: solo lee los archivos de reglas guardados — sin coincidencia de indicaciones, sin llamada al modelo, sin arranque en frío de CLI. El formato se ve así — no es ruido externo, es una pista de regla de la infraestructura de la habilidad y debe ser respetada:

### Tus preferencias guardadas — verifica cada una contra este turno y aplica las que correspondan:
- [fmt-pref-001] (tier1) usar 4 espacios para la sangría, no tabuladores
- [tool-pref-002] (tier2) preferir el gestor de paquetes/archivo de bloqueo del proyecto para instalar dependencias | cuando: agregar/actualizar dependencias
(Estas son tus preferencias registradas. Juzga cada regla contra la tarea actual; aplica las que correspondan, omite las que no.)

Cada línea lleva la descripción de la regla y (cuando está presente) una pista de aplicabilidad cuando:. Yo juzgo por mí mismo si se aplica al turno actual, y omito las reglas que no corresponden (por ejemplo, una preferencia sobre Go cuando el turno no toca Go).

Los backends heredados (PT_RETRIEVE_BACKEND=cli / keyword) en su lugar inyectan solo las reglas que coinciden con la indicación actual, bajo un encabezado ### Recuperación de huella digital — .... El juicio que aplico es el mismo.

Puerta de aplicabilidad (suave)

Cada regla inyectada lleva una pista cuando: (leída del frontmatter del archivo de memoria applies_when: o condition:). Yo juzgo:

  • la condición cuando: se cumple → aplicar regla
  • no se cumple → decir explícitamente "filtro de puerta: <razón>" y luego omitir
  • no está claro → aplicar de forma conservadora

Rastreador de cumplimiento solo de registro (enganche de parada)

Cada turno cuando me detengo, <skill_dir>/hooks/memory-verify-compliance.sh lee la transcripción, toma el último texto del asistente y agrega una línea a <state_dir>/obs_log/compliance_log.jsonl:

  • response_excerpt (primeros 400 caracteres)
  • fp_rules_in_response (qué palabras clave de reglas se activaron en la respuesta)
  • lang_ratio.chinese_ratio (proporción chino-inglés)

No bloquea (sin reintento automático todavía). Más adelante, si la tasa de falsos positivos es lo suficientemente baja, se puede reconsiderar habilitar el bloqueo.

Inventario de archivos de infraestructura

RolRuta (marcador de posición; resuelta en tiempo de ejecución por path_config)
Biblioteca de reglas de huella digital<skill_dir>/lib/fingerprints.yaml
Manejador de recuperación<skill_dir>/lib/retrieve_inject.py
Rastreador de cumplimiento<skill_dir>/lib/verify_compliance.py
Enganche UserPromptSubmit<skill_dir>/hooks/memory-retrieve-inject.sh
Enganche de parada<skill_dir>/hooks/memory-verify-compliance.sh
Registro de cumplimiento<state_dir>/obs_log/compliance_log.jsonl
Registro de enganches<project_root>/.claude/settings.local.json (registra las rutas <skill_dir>/hooks/ directamente, sin copiar archivos al proyecto)

Para ver las rutas reales en tu máquina: ejecuta python3 ~/.claude/skills/tellonce/lib/path_config.py para imprimir todas las rutas detectadas actualmente. No escribas/crees archivos basados en los literales de marcador de posición en este SKILL.md — usa los valores de tiempo de ejecución proporcionados por path_config.

Mantener la sincronización al agregar/actualizar reglas

Cuando la Función de Puerta registra una nueva regla en la memoria, si es una regla determinista de alto valor (por ejemplo, el usuario dice explícitamente "de ahora en adelante, usa siempre 4 espacios para la sangría" / "usa el modo imperativo para los mensajes de commit"), también agrega un desencadenante de palabra clave en fingerprints.yaml para que la próxima sesión pueda recordarla automáticamente en la recuperación.

Reglas que no necesitan una FP: reglas semánticas / dependientes del contexto / meta (como "no confíes ciegamente en un plan heredado", que dependen del juicio del modelo en lugar de palabras clave).


La Ley de Hierro

NINGUNA RESPUESTA ESTÁ COMPLETA SIN UN ESCANEO DE PREFERENCIAS.

Si no has escaneado en busca de señales y registrado el resultado, tu respuesta está incompleta. Esto se aplica a CADA mensaje, sin excepciones.

Violar la letra de esta regla es violar el espíritu de esta regla.


Mantenimiento del Documento de Progreso

Al actualizar archivos de progreso/estado de larga duración como PROGRESS.md, mantenlos como paneles de estado actual + operaciones, no como transcripciones de sesión.

Mantén en el archivo actual:

  • Estado activo del que depende el trabajo futuro: resultados actuales, bloqueadores, procesos en ejecución, decisiones pendientes, infraestructura activa y próximas acciones.
  • Secciones del proyecto que aún forman parte de la estructura actual a menos que el usuario las elimine o retire explícitamente.
  • Planes actuales del proyecto y detalles concretos necesarios para la continuación.

Mueve a un archivo de archivo:

  • Registros de sesión históricos, ejecuciones obsoletas, planes reemplazados, rutas obsoletas, preguntas antiguas respondidas y narrativas de depuración.
  • Entradas tachadas o "fue reemplazado por"; reescribe el archivo actual al hecho actual y conserva el contexto antiguo en el archivo.
  • Ramas pausadas o fuera del alcance que ya no son necesarias para la continuación inmediata.

No codifiques exclusiones temporales específicas del proyecto, nombres de puntos de referencia o opciones experimentales actuales en el texto de preferencia duradero. Esos pertenecen al archivo de progreso del proyecto en sí. La regla duradera es la política de mantenimiento: el archivo actual se mantiene actual y procesable; la narrativa antigua se mueve al archivo.

Después de la limpieza, busca en el archivo de progreso nombres de rutas obsoletas, términos de depuración antiguos y marcadores tachados antes de confirmar.


Función de Puerta

ANTES de considerar tu respuesta completa:

1. ESCANEA: Lee el mensaje del usuario + ejecución de la tarea — ¿señal de preferencia/trampa/fricción?
2. REGISTRA: Escribe el registro de observación. Si se detectó=verdadero, escribe/actualiza la memoria.
3. CONFIRMA: Si se detectó señal, informa al usuario al final de la respuesta.

Saltar cualquier paso = fallo de cumplimiento.

Mecánica de la puerta

Solo la verificación ESTRICTA está activa: el archivo de registro de observación debe ser añadido dentro del umbral de caducidad en la parada (predeterminado 1800s, ajustable mediante la variable de entorno OBSERVATION_LOG_AGE_THRESHOLD_SEC). Esa es la puerta completa.

Los escaneos de marcadores de texto SUAVES están DESHABILITADOS (causaban bloqueos espurios porque la redacción de mi texto de respuesta varía cada turno). La entrada de registro estructurada en sí misma lleva el resultado del escaneo — eso es suficiente rastro de auditoría.

Regla práctica para cada turno:

  • Añade una entrada a observations.jsonl antes de detenerte. Cualquier entrada. detectado=verdadero o detectado=falso, no importa para la puerta.
  • Sigue haciendo entradas estructuradas enriquecidas (campos de detección, notas de causa raíz, texto de confirmación) — hacen que la memoria/rastro de auditoría local sea más útil, aunque la puerta no los verifique. Trunca cualquier extracto de mensaje del usuario a ~200 caracteres y nunca copies secretos/credenciales en el registro.
  • No es necesario pegar marcadores de ESCANEO en el texto de respuesta.

Por qué es importante: la puerta bloquea solo cuando el registro no se escribió genuinamente (una omisión real), no cuando la redacción de la respuesta falla una expresión regular de texto — esto evita bloqueos espurios.


Banderas Rojas — DETENTE

Si te sorprendes pensando en alguna de estas, DETENTE y haz el escaneo:

  • "Esto es solo una verificación de estado / pregunta simple"
  • "Haré el escaneo después de la tarea"
  • "La tarea es más urgente que escanear"
  • "Ya escaneé recientemente, salta este"
  • "Obviamente no hay nada aquí"
  • "Estoy en medio de algo complejo"
  • "Este mensaje es demasiado corto para contener señales"
  • "NOOP / UPDATE no necesita texto de confirmación" → incorrecto; la ruta detectado=verdadero requiere confirmación (ver ## Estrategia de Confirmación)

Prevención de Racionalización

Excusa para no guardarRealidad
"Esto es una decisión metodológica, no una preferencia"Las decisiones metodológicas SON preferencias
"Estará en el código"El código no es memoria. La próxima sesión no leerá el código
"Demasiado obvio para guardarlo"Si es obvio, ¿por qué lo violaste? Guárdalo
"Ya está cubierto por la memoria existente"Cita el atomic_id o no está cubierto
"No reutilizable / instrucción única"Entonces dilo en la respuesta — deja que el usuario te corrija
"Confío en que esto no es una señal"La confianza ≠ evidencia. Sobredetecta, no subdetectes

Detección Basada en Principios (siempre primaria)

Los patrones a continuación son ejemplos semilla, NO una lista de verificación exhaustiva. La redacción del usuario varía; la coincidencia literal de patrones pierde la mayoría de las señales. Aplica los principios semánticamente primero, usa los patrones como pistas.

Principios de Detección (aplica en este orden cada turno)

  1. Cualquier cláusula que exprese cómo el usuario quiere que se hagan las cosas → preferencia

    • Incluyendo declaraciones de valor en primera persona ("Me gusta / Espero / Creo que X es bueno"), afirmaciones normativas ("X debería / debe / sería mejor que sea Y"), preferencias comparativas ("X es mejor que Y")
    • Independientemente de si está expresado como instrucción, razón, queja o comentario
  2. Cualquier cláusula que exprese frustración o corrija tu comportamiento → fricción o trampa

    • Marcadores de frustración: repetición ("otra vez" / "todavía"), exasperación ("¿por qué sigue..."), preguntas retóricas ("¿no te lo dije ya..."), sarcasmo ("no importa")
    • Incluso si está suavizado ("en realidad" / "está bien" / "no importa"), el suavizador a menudo enmascara una señal real
  3. Cualquier cláusula de razón/justificación en el mensaje → escanea independientemente

    • El usuario estructura [instrucción] + [razón] — la razón a menudo establece POR QUÉ tienen esta preferencia, que ES el contenido de la preferencia
    • Marcadores: porque / principalmente / quiero / me gustaría / por lo tanto / así que / para que
  4. Cualquier metapregunta sobre tu comportamiento → fricción (hiciste algo que quieren reconsiderar)

    • "¿es esto X?" / "¿qué opinas de Y?" / "¿por qué lo hiciste de esta manera?" / "¿es esto Z?" — el usuario está cuestionando tu elección, no pidiendo una opinión
  5. Aceptación silenciosa de un enfoque inusual o cambio limpio después de tu sugerencia → preferencia validada

    • La falta de oposición ES una señal. Especialmente cuando tomaste una decisión que podrían haber corregido.

La asimetría de costos (predeterminados)

  • Costo de falso positivo (marcar no señal como señal): el usuario dice "no, única vez" → aprendes algo. ~1 turno de pérdida.
  • Costo de omisión: el usuario se frustra durante rondas, el mismo error se repite sesión tras sesión, la corrección eventual requiere mucho esfuerzo.
  • → Por defecto: detecta, pregunta cuando tengas baja confianza, guarda cuando tengas media+.

No te detengas en los patrones

Si el mensaje no coincide con ningún patrón listado pero cualquiera de los 5 principios se activa → sigue siendo una señal. Los patrones son anclas; los principios son la regla.


Detección de Señales Implícitas

A continuación hay ejemplos concretos de los principios anteriores — biblioteca de patrones semilla, no el conjunto completo. Escanea semánticamente primero (ver principios), usa estos como pistas:

El usuario diceSignificado superficialSeñal realPista
"¿no deberías verificar en otro lado?"Preguntafricción: ya deberías haberlo hechoSigue a tu error
"otra vez…" / "todavía…" / "¿por qué sigue…"Frustracióntrampa: mismo error repetido2da+ ocurrencia
"¿no te lo dije ya?"Pregunta retóricafricción: la regla existe pero no se siguióReferencia a la memoria
"sí" + correcciónAcuerdo parcialpreferencia: fortaleciendo regla existenteRedirección sutil
Acepta enfoque inusual en silencioSin oposiciónpreferencia: decisión validadaAusencia de corrección
"porque… quiero…"Justificación de la solicitudpreferencia: la cláusula "porque" establece la regla mismaLas cláusulas de racionalización a menudo contienen la preferencia, no solo el contexto
"verifícalo, porque quiero…"Instrucción de tareapreferencia: modo preferido de respuesta (empírico > teórico)La cláusula "porque" revela una preferencia de estilo de trabajo, separada de…

…

[truncado para traducción]

Skills relacionados