TongyiDai/feishu-okr-drafter

Redactor de OKR para Feishu

Objetivo y límites

Organizar hechos laborales de múltiples fuentes en OKR de Feishu que sean discutibles, medibles y alineables, y, tras autorización explícita del usuario, escribirlos como borrador y mencionar a los colaboradores correspondientes. La interfaz se usa para agilizar, pero las páginas de Feishu, documentos históricos, capturas de pantalla, contenido pegado por el usuario y resúmenes de trabajo también son entradas válidas. Por defecto, primero completa la evaluación y el borrador, sin crear, publicar ni modificar OKR existentes.

Cumple tres reglas fundamentales:

• No rellena valores objetivo, líneas base, fechas límite, responsables, resultados comerciales u objetivos de alineación que falten; la información ausente se escribe como [pendiente de confirmar].
• Informa por separado las acciones de borrador, escritura, guardado y publicación; si no hay evidencia de lectura de vuelta, no declara la tarea como completada.
• Cuando se manejan datos sensibles de ingresos, costos, clientes, personal o estrategia, usa proporciones, intervalos, tasas de finalización o expresiones anonimizadas que hayan sido confirmadas, y marca las partes que requieren comunicación por separado.

Flujo de trabajo

1. Determinar el modo de tarea

Identificar lo que el usuario quiere hacer:

1. Generar un nuevo borrador a partir de notas de trabajo;
2. Modificar O/KR existentes;
3. Revisar la calidad y las relaciones de alineación;
4. Escribir el borrador en Feishu;
5. Ajustar objetivos, KR, pesos o fechas límite dentro del ciclo.

Si no hay una intención clara de escritura, permanecer en modo solo lectura y borrador.

2. Establecer contexto y rutas de datos

Primero, leer las descripciones de versión actual de lark-shared y lark-okr. Al leer contenido de Feishu, ejecutar verificación de identidad, tenant y permisos:

lark-cli auth status --json --verify
lark-cli contact +get-user --as user

En entornos que admitan auth status --json --verify, se debe confirmar identity=user y verified=true. Si la compilación actual de CLI no tiene el subcomando auth, se puede recurrir a contact +get-user --as user para resolver el usuario actual; si es necesario continuar en modo borrador, usar task +get-my-tasks --as user para demostrar que el contexto de usuario es legible. Antes de escribir realmente OKR o mencionar colaboradores, aún se debe confirmar el usuario objetivo y el tenant.

Seleccionar las rutas de datos disponibles en el siguiente orden; no se debe tratar "la interfaz no está disponible" como un punto final de la tarea:

1. Ruta de interfaz/CLI: cuando los permisos lo permitan, usar la interfaz para leer en lote ciclos, O/KR, indicadores, progreso y relaciones de alineación.
2. Ruta de página de Feishu: cuando falte la interfaz, el alcance sea insuficiente o sea necesario confirmar el estado de guardado de la página, usar control-in-app-browser. Priorizar tomar el control de la página de OKR que el usuario tenga abierta actualmente; si no hay ninguna página disponible, hacer una única navegación explícita a la entrada de OKR de Feishu. Leer según la página visible, sin adivinar URL, orden de campos ni significado de botones.
3. Ruta de materiales del usuario: leer texto, capturas de pantalla, documentos, minutas de reuniones, resúmenes de rendimiento, autoevaluaciones H1 y revisiones de trabajo proporcionados por el usuario.
4. Ruta de documentos de Feishu: buscar y leer documentos de Feishu accesibles en el tenant actual relacionados con la definición, redacción, alineación, asistentes de llenado y ejemplos de roles para OKR.

Incluso si la interfaz tiene éxito, combinar con la página o el texto original para verificar estados clave; si la página tiene éxito, conservar los hechos de la página y no descartar evidencia solo porque no se pueda formar un ID de API.

Obtener según sea necesario:

• Ciclo objetivo del usuario actual: okr +cycle-list;
• O/KR del ciclo: okr +cycle-detail;
• Indicadores de O y KR: objective.indicators list, key_result.indicators list;
• Relaciones de alineación de O: objective.alignments list;
• Registros de progreso relacionados: okr +progress-list;
• Documentos de Feishu relacionados: buscar OKR, definición, redacción, alineación, asistente de llenado, priorizando la lectura de normas y ejemplos accesibles en el tenant actual.

La determinación del ciclo se basa principalmente en la superposición de fechas de inicio y fin con la fecha actual, y luego se refiere al estado del ciclo; cuando el usuario no lo solicita explícitamente, no se toma el ciclo anual como ciclo actual por defecto.

Si falta el alcance específico de OKR, dejar de reintentar ciegamente, explicar el alcance faltante y su impacto. Se puede continuar generando un borrador basado en los materiales de trabajo proporcionados por el usuario y los documentos de Feishu a los que se tenga permiso de lectura, marcando los límites del contexto.

2.1 Uso de materiales históricos

Los OKR históricos son una referencia clave. Al menos revisar el ciclo completado más reciente; cuando sea posible, examinar ciclos anteriores, registros de progreso, calificaciones, comentarios, resúmenes de rendimiento y autoevaluaciones H1.

Clasificar el contenido histórico en cuatro categorías:

• Hechos completados: se usan como línea base, prueba de capacidad o evidencia de caso; no se copian textualmente como nuevos KR;
• Elementos de alta prioridad no completados o recurrentes: se convierten en candidatos principales para el ciclo actual, redefiniendo resultados de etapa;
• Comentarios repetidos de superiores o colegas: se transforman en resultados de calidad, colaboración o mecanismo;
• Capacidades ya formadas pero no replicadas: se convierten en resultados de escalabilidad, estandarización, capacidad de ejecución independiente por otros o resultados comerciales.

Crear un registro de fuentes breve: hecho → fuente → momento → impacto en el nuevo O/KR → si aún necesita confirmación. Separar los logros pasados de los compromisos futuros.

2.2 Lectura de cuatro tipos de contexto de relaciones de OKR

Antes de escribir los OKR del ciclo actual, verificar siempre los siguientes cuatro tipos de relaciones; cuando falte la interfaz, completar mediante páginas de OKR de Feishu, capturas de pantalla, contenido pegado por el usuario o documentos accesibles:

1. Finalización del ciclo anterior del usuario: comparar uno por uno los valores objetivo, progreso, calificaciones, comentarios y resultados reales de O/KR. Distinguir entre completado, parcialmente completado, no completado, cambio de objetivo y evidencia faltante; solo incluir elementos no cerrados que aún tengan significado para el ciclo actual o nuevos resultados de etapa.
2. Menciones (@) al usuario en el ciclo actual: recopilar en qué O/KR fue mencionado, por quién, qué expectativas de colaboración implica, plazos de entrega y límites de responsabilidad. Clasificarlos como candidatos principales, colaboradores, elementos a confirmar o menciones informativas; no interpretar automáticamente una mención como un compromiso.
3. Menciones (@) del usuario a otros en el ciclo anterior: revisar a quién mencionó el usuario, los O/KR correspondientes, el contenido de la colaboración y si se completó el cierre. Identificar dependencias continuas, búsquedas repetidas de personas, desajustes de colaboración y relaciones que pueden consolidarse como mecanismos; para el ciclo actual, conservar solo las relaciones de colaboración que aún sean válidas.
4. OKR del supervisor directo: confirmar la identidad del supervisor directo, el ciclo actual, el orden de O/KR, los resultados clave, la métrica de indicadores y los límites de colaboración. Determinar si el O personal es de asunción, soporte, colaboración horizontal o línea principal independiente; cuando falten los OKR del supervisor, el ciclo sea incierto o la identidad no pueda verificarse, marcar los límites sin hacer inferencias propias.

Crear un registro de relaciones: tipo de relación → objeto de origen → O/KR → contraparte/colaborador → hecho o expectativa → tratamiento en el ciclo actual → si ya está confirmado. Usar los cuatro tipos de información como "resultado histórico", "entrada de colaboración", "retrospectiva de colaboración" y "asunción vertical", evitando mezclarlos en una sola lista de tareas.

3. Recopilar la entrada mínima necesaria

Al menos confirmar: ciclo, rol o ámbito de responsabilidad, resultado comercial a alcanzar, línea base conocida, valor objetivo o criterio de evaluación, principales colaboradores, restricciones e información sensible.

Cuando ya existan OKR de superiores o del equipo, identificar primero:

• Qué O necesitan ser asumidos;
• Qué KR son colaboración entre pares;
• Qué trabajo es responsabilidad principal del usuario y cuál es de asistencia;
• Si el trabajo propuesto por el usuario se superpone o entra en conflicto con O existentes.

Si existe un supervisor directo, los OKR del ciclo actual del supervisor son la referencia principal para la asunción vertical; los OKR del equipo, de pares y el contenido de menciones se usan para complementar el alcance de la asunción y los límites de colaboración. Las menciones (@) hechas y recibidas y "parecer relevante" solo pueden formar relaciones candidatas; solo cuando el contenido, la responsabilidad principal, el ciclo y la confirmación mutua se cumplan, se reporta como alineado.

Cuando falten entradas clave, hacer las mínimas preguntas necesarias para completar; si aún no se puede confirmar, continuar con la salida pero poner la incertidumbre explícitamente en [pendiente de confirmar].

4. Generar borrador

Cómo escribir el O

• Enfocarse en trabajo de alta prioridad y alto valor, excluyendo la acumulación de responsabilidades diarias; se recomiendan 3–5, menos cuando el alcance del trabajo sea estrecho.
• Describir claramente la dirección, el valor esperado y el marco de tiempo; mantener una granularidad moderada, evitando eslóganes o listas de tareas.
• Mantener cierto nivel de desafío, evitando convertir "seguir haciendo" en un objetivo.
• Dividir elementos a largo plazo en resultados de etapa para el ciclo actual.
• Usar vocabulario comercial que sea comprensible para un lector en la primera lectura; mantener los términos propios ya confirmados por la organización.

Cuando el usuario enumere varios proyectos o campañas de una vez, primero agrupar por resultados comerciales, luego decidir el número de O. Los nombres de proyectos generalmente entran en KR, rutas de implementación o columna de evidencia; solo cuando representen una línea principal de resultados independiente deben ser un O por sí mismos. Las direcciones de agrupación comunes incluyen: resultados de cliente/comerciales, eficiencia de procesos de extremo a extremo, productización y replicación, mecanismos organizativos e influencia.

Cómo escribir el KR

• Se recomiendan 3–5 por O, cada uno cubriendo diferentes aspectos clave de soporte.
• Primero escribir el resultado y el estado, luego agregar las rutas de implementación necesarias; evitar escribir solo "completar, responsable, impulsar, dar seguimiento".
• Proporcionar criterios de evaluación objetivos, cualitativos o cuantitativos, observables; después de "mejorar, optimizar, potenciar", completar el punto de partida, punto final o condición de aceptación.
• Indicar los hitos de tiempo dentro del ciclo; cuando se desconozca el valor objetivo, dejar [valor objetivo pendiente de confirmar].
• Cuando sea necesaria colaboración, indicar el responsable principal, los colaboradores y los límites de responsabilidad; los colaboradores principales generalmente no deben exceder 4 personas.
• Si es necesario explicar la dirección del KR, usar subtítulos breves, por ejemplo [Valor para el cliente], [Mejora de procesos], evitando combinar múltiples líneas principales en una sola.

Priorizar la siguiente estructura para organizar un KR:

[Aspecto clave] Mediante [ruta necesaria], para [hito de tiempo] alcanzar [resultado observable/valor objetivo], a cargo de [responsable principal], con la colaboración de @ [colaborador].

Acortar la ruta si es demasiado larga; el resultado, el tiempo y los criterios de aceptación deben mantenerse obligatoriamente.

5. Ejecutar verificación de calidad

Revisar cada O y KR por separado, y clasificar los problemas en "bloquea la publicación" y "optimización sugerida". Las reglas detalladas están en references/okr-writing-principles.md.

Puntos clave de verificación:

• Si el O es de alta prioridad, claro, moderadamente desafiante y corresponde al ciclo actual;
• Si el KR soporta directamente al O, describe un resultado, es medible, alcanzable y tiene límite de tiempo;
• Si hay KR que se repiten, omiten aspectos clave de soporte o entran en conflicto;
• Si los valores objetivo, líneas base, fechas y responsables tienen fuente;
• Si existe asunción vertical, colaboración horizontal, responsabilidad principal clara y objetos de alineación reales;
• Si se ha verificado la finalización del ciclo anterior, las menciones (@) del ciclo actual, menciones del ciclo anterior a otros y los OKR del supervisor directo;
• Si se mantiene consistencia en el orden de los objetivos, términos propios, privacidad y manejo de información sensible;
• Si se está confundiendo puntuaciones, progreso, pesos y valores objetivo.

6. Entregar borrador

Entregar en el siguiente orden:

1. Ciclo y contexto: qué ciclos, O de superiores, documentos y entradas de usuario se usaron; explicar los límites de lectura.
2. Borrador de OKR: para cada O, listar KR, criterios de resultado, tiempo, responsable principal, colaboradores y fuentes de evidencia.
3. Herencia histórica: qué hechos históricos se convirtieron en línea base, qué elementos continúan, qué resultados se elevaron a resultados de replicación o escalabilidad.
4. Lista de relaciones y herencia: finalización del ciclo anterior, menciones (@) del ciclo actual, menciones del ciclo anterior a otros, herencia del supervisor directo, objetos sugeridos para mencionar (@), conflictos y asuntos pendientes de comunicación.
5. Diagnóstico de calidad: elementos que bloquean, sugerencias de optimización, hipótesis aún no verificadas.
6. Pendiente de confirmar: solo incluir elementos que cambiarían el significado del objetivo, los criterios de resultado o la escritura en el sistema.

Prohibido usar un conjunto de números aparentemente completo para ocultar incertidumbre. El juicio de calidad debe explicar "por qué este KR demuestra que se alcanza el O".

7. Escribir en Feishu

Solo ejecutar operaciones de escritura cuando el usuario lo solicite explícitamente. Antes de escribir:

1. Confirmar nuevamente el usuario actual, tenant, ciclo, pertenencia del objetivo y borrador completo;
2. Crear una "lista de escritura y menciones": para cada O/KR, los colaboradores correspondientes, el motivo de la mención (@), los límites de responsabilidad principal, la fuente y el estado de verificación;
3. Para cada nombre o correo electrónico, usar lark-cli contact +search-user para resolverlo en open_id. Si hay múltiples candidatos, cruce de tenant o información de identidad insuficiente, detener esa mención (@) y solicitar confirmación, no adivinar;
4. Primero usar --dry-run para verificar la solicitud;
5. Para texto normal y menciones, usar preferentemente el estilo simple; cuando se necesite control preciso de la posición de la mención, usar el elemento mention de richtext;
6. Para crear múltiples O/KR nuevos, usar preferentemente okr +batch-create; para un solo O o KR, usar okr +create; colocar la mention en el O/KR correspondiente, evitando concentrar todas las menciones en un solo objetivo;
7. No establecer puntuaciones automáticamente por ser un "borrador"; solo procesar puntuaciones cuando el usuario lo solicite explícitamente;
8. Después de escribir, volver a leer los detalles del ciclo para verificar la cantidad de O/KR, el contenido, el orden, los pesos, las fechas límite, las menciones y el estado de guardado/publicación;
9. Si la lectura de vuelta es incompleta, la mención no se ha materializado o la semántica del sistema podría publicar directamente, detenerse y explicar al usuario, sin continuar.

Determinación de escritura y menciones

• Cuando el usuario solo dice "redactar, generar, optimizar", solo entregar un borrador local y una lista de sugerencias de menciones (@).
• Cuando el usuario dice explícitamente "escribir, guardar en Feishu, rellenar por mí", se puede crear un borrador; cuando el usuario también menciona explícitamente "mencionar a alguien" o el registro de relaciones ya tiene colaboradores verificados, entonces escribir la mención.
• La mention es un ID de usuario real, no una cadena @nombre en el texto. En la ruta de interfaz, colocar mention: ["ou_xxx"] en el O/KR correspondiente; en la ruta de página, usar el selector de usuarios y leer la etiqueta de usuario real en la página.
• Explicar por separado el motivo de la mención (@) para el responsable principal, los colaboradores y el supervisor directo; las relaciones candidatas formadas solo por "relevante" o "mencionado" deben ir primero a la lista de pendientes de confirmar.
• Informar los resultados de escritura por separado: creado/guardado, mencionado, no mencionado y motivo, sin publicar. Si no hay evidencia de lectura de vuelta para alguno de estos, mantenerlo como pendiente de verificación.

Cuando la interfaz no pueda escribir, se puede usar "Pegar OKR en lote" o los controles de edición de página en la página de OKR de Feishu ya iniciada para guardar el borrador. La ruta de página debe seguir el siguiente orden:

1. Confirmar primero el usuario actual, el ciclo y el título de la página;
2. Después de pegar O/KR, revisar la vista previa de análisis para confirmar la cantidad y jerarquía de O/KR; cuando el pegado en lote no pueda generar menciones reales, usar los controles de edición de página para seleccionar colaboradores uno por uno;
3. Para cada O/KR que necesite mención (@), usar el selector de usuarios de la página, verificar el nombre mostrado y el departamento, evitando solo ingresar texto plano @nombre;
4. Solo ejecutar la confirmación de guardado, no hacer clic en publicar;
5. Volver a la página final para verificar "guardado", el contenido de O/KR y las etiquetas de usuario reales, y confirmar que cada objetivo aún tenga el botón "publicar";
6. Si la ventana emergente de la página se cierra, falta el mensaje de guardado, la etiqueta (@) no aparece o la cantidad de campos es anormal, volver a leer la página, sin declarar que el guardado fue exitoso.

La relación de alineación solo actúa sobre el Objective. Antes de crear una alineación, confirmar que los dos objetivos pertenecen a objetivos diferentes, que los ciclos tienen superposición de tiempo y que efectivamente existe una relación de asunción o colaboración; no escribir "relacionado" directamente como "alineado". El proceso completo está en references/okr-alignment-review.md.

Enrutamiento de referencias

• Principios de redacción, diagnóstico de O/KR y contraejemplos: leer references/okr-writing-principles.md.
• Alineación y manejo de conflictos antes, durante y después de la reunión: leer references/okr-alignment-review.md.
• Entidades, lectura, escritura, permisos y lectura de vuelta de OKR en Feishu: leer references/feishu-okr-operations.md.