Cuando el 92 % significa cosas diferentes
Un estudio de caso de redacción UX sobre cadenas de texto que definen su propio contexto en una interfaz de texto sin formato.
Sweepy es una herramienta de búsqueda de empleo basada en terminal. La interfaz se dibuja con caracteres de dibujo de cuadros y texto en color, y lee la entrada del teclado. La explicación debe estar presente en el propio texto, ya que no hay espacio para que aparezca una descripción emergente. El panel de inicio recorta su línea de estado en el borde del marco en lugar de ajustar el texto. Una cadena o bien termina dentro del ancho disponible o bien pierde su final.
De ahí surgió una regla: Cada cadena indica su propio contexto. Las etiquetas de puntuación indican quién ha introducido el número. El texto de estado sigue la misma disciplina, desde la línea inferior del lanzador hasta la sugerencia de formato de cada solicitud. La puntuación es el caso más complicado, porque un porcentaje parece informativo independientemente de si el lector sabe cómo lo ha calculado la herramienta.
Dos porcentajes, dos preguntas
Sweepy puntúa una publicación en comparación con un currículum de dos formas diferentes.
La primera es el sistema de puntuación determinista, y cada barrido lo ejecuta. sweepy abre el Launchpad y START SWEEP puntúa cada ficha que encuentra el barrido. sweepy --run repite el último perfil guardado sin abrir el asistente. Esta pasada compara dos documentos. Cuenta las palabras compartidas entre el currículum y la oferta de empleo, combinando la coincidencia de requisitos en un 60 % con la coincidencia de palabras clave en un 40 %, y luego escala el resultado por resume.keywords_weight. Un término solo cuenta cuando aparece en ambos documentos. El evaluador nunca razona sobre si el lector podría desempeñar el puesto.
La segunda es una evaluación por parte de un agente, disponible a través del Protocolo de Contexto del Modelo (MCP). Un agente lee conjuntamente el currículum analizado y la oferta de empleo, y luego razona sobre en qué medida el lector se ajusta al puesto. Envía su propio porcentaje a través de submit_judgments.
El recuento de palabras compartidas y el juicio del agente responden a preguntas diferentes. El recuento de palabras compartidas mide la coincidencia, no la adecuación, por lo que la etiqueta debe identificar al autor. El recuento indica cuánto texto comparten el currículum y la oferta de empleo. El agente evalúa en qué medida una persona se adapta a un puesto de trabajo. Un currículum puede repetir palabra por palabra el texto de la oferta de empleo y, aun así, indicar una escasa adecuación. Un currículum redactado con otro vocabulario puede indicar una gran adecuación. El recuento de palabras detecta el primer caso y pasa por alto el segundo, mientras que el agente puede sopesar ambos.
La ficha muestra una puntuación. El autor más reciente la establece, y una evaluación vuelve a clasificar el informe en función del nuevo valor. La valoración sustituye a la puntuación determinista en lugar de aparecer junto a ella. Un simple porcentaje oculta cuál de las dos opciones tiene el lector.
El texto debía indicar el autor dentro de la línea de la insignia, antes de que el lector abriera una ficha. El resto de la interfaz sigue la misma regla.
De la plataforma de lanzamiento a los resultados
El flujo sigue el orden: plataforma de lanzamiento → asistente de configuración → barrido → resultados. Cuando un barrido supera el límite de llamadas a herramientas del cliente, pasa a un estado consultable que permanece activo hasta que finaliza la ejecución.
Las tarjetas 3 a 8 siguen ese orden. La tarjeta 2 muestra la puntuación, que solo aparece una vez finalizado el barrido y es el objetivo hacia el que se dirige el resto de la página. La tarjeta 1 expone el problema, y la tarjeta 9 describe la restricción que subyace a cada cadena de caracteres entre ambas.
Un espacio para la puntuación, dos autores
Un espacio para la puntuación, dos posibles autores. Cada barrido puntúa cada tarjeta con el recuento determinista de solapamientos. Pero una evaluación del MCP sobrescribe esa cifra con su propio razonamiento. Sin una diferencia clara en el etiquetado, un lector no puede saber qué autor ha establecido la puntuación, y no puede calibrar la confianza. El problema de contenido consistía en diferenciar al autor dentro de la línea de la insignia, en el espacio de unas pocas palabras.
Distinguir un recuento de un juicio
Mismo perfil, mismo número, dos autores. Un agente estableció la primera tarjeta, por lo que se lee 92% MATCH. El evaluador determinista estableció la segunda, por lo que reza 92% KEYWORD OVERLAP. La etiqueta identifica al autor. Un lector que solo vea el 92 % no tiene forma de distinguir entre ambos. La evaluación sobrescribe la puntuación de solapamiento en el mismo espacio, ya que el recuento y la valoración responden a preguntas diferentes.
92% KEYWORD OVERLAPse refiere al recuento de palabras compartidas, comparando el currículum con la oferta de empleo.92% MATCHse refiere a la cifra a la que ha llegado un agente tras evaluar en qué medida el lector se ajusta al puesto.
Un barrido escribe el recuento en cada tarjeta que genera, tanto si se inicia en la terminal como a través de run_sweep en MCP. Solo un match_pct enviado lo sustituye por MATCH.
La línea de clasificación del PDF repite la etiqueta entre corchetes: #1 // EMPRESA | [92% MATCH] o [92% KEYWORD OVERLAP]. El CSV escribe match_value junto a match_kind, lo que proporciona al lector la misma información en un formato legible por máquina. Puede aparecer una tercera puntuación junto a la puntuación de coincidencia. [88% PORTFOLIO FIT] muestra su propia etiqueta por la misma razón: tus muestras responden a una pregunta diferente a la que responde tu currículum.
La insignia de la solicitud muestra primero el texto y, en segundo lugar, el color. [STANDARD / QUICK APPLY] indica un envío estándar, y [EXTENDED RESPONSES REQUIRED] señala un puesto que requiere muestras de redacción. La tercera tarjeta muestra [EXTENDED RESPONSES REQUIRED] en una línea de clasificación que también incluye la pista del currículum. Ambas etiquetas funcionan sin color, lo cual es importante para la accesibilidad y para los terminales que no lo visualizan.
Identidad, alcance y estado de preparación en una sola línea
Current profile: none loaded / build one to start indica la ausencia de perfil y la siguiente acción en una sola línea. Current profile: Alex Rivera / 4 titles / Ready confirma el nombre en el primer campo y el estado de preparación en el último. Cada barra separa una respuesta de la siguiente, y la línea se recorta en el borde del marco en lugar de ajustarse. Resume missing sustituye a Ready cuando el perfil guardado no tiene ruta de currículum.
En un terminal, la línea de estado es el único contexto persistente. Se lee a la vez como un encabezado y como un indicador de disponibilidad.
Verbo, objeto y, a continuación, el objetivo del lector
START SWEEP se combina con Run your job search now. Cada mosaico muestra dos líneas: un nombre y un subtítulo que reformula lo que hace Enter en palabras del lector. SWEEP SETTINGS dice Ranking, cards, tracking. SWEEPY'S TOOLBOX dice Edit profile, logs, help. EXIT SWEEPY dice Save changes and close, lo que garantiza que se conservará tu trabajo.
Los mosaicos de acción comienzan con un verbo y su complemento directo. Los demás indican un lugar o una salida. Un subtítulo explica cualquier término interno en lenguaje sencillo. Los números de dos dígitos identifican cada casilla en lugar de ordenar la cuadrícula. La fila superior empareja la 01 con la 04. Una casilla se añade a la cuadrícula sin renumerar las demás. La navegación se realiza con las teclas de flecha y la tecla Intro.
Sugerencias de formato dentro de la indicación
Una indicación mantiene la pregunta en una sola línea y, cuando el formato es importante, coloca la regla debajo, sangrada:
What job titles are you looking for?
(Separate multiple titles with a comma)
La indicación sobre el salario indica la opción de omitir dentro de la propia pregunta:
What is your minimum target salary? (Leave blank to skip):
La regla aparece en la línea donde se toma la decisión. El lector permanece en la pantalla. Un terminal no dispone de información sobre herramientas a la que recurrir.
Editar una respuesta sin volver a ejecutar el asistente
El asistente consta de quince pasos, y la tecla Esc permite retroceder una pregunta cada vez. La pantalla de revisión muestra once entradas: ← Atrás, luego Submit profile y, a continuación, nueve acciones. Edit an answer se encuentra justo debajo de Submit profile. La opción de edición está a una línea de distancia del envío. Un usuario que quiera cambiar una respuesta no tiene que volver a ejecutar cada mensaje.
Etiquetas de fase para los cinco pasos
Una ejecución desde la línea de comandos marca cinco fases numeradas, cada una de las cuales indica la tarea.
[1/5] Loading profile...
[2/5] Discovering roles...
[3/5] Validating URLs...
[4/5] Scoring against resume...
[5/5] Generating reports...
Las líneas del registro indican el número de etapa. La información de progreso de MCP, en cambio, nombra el elemento: «paso 1» de «un total de 4» para el primero de los cuatro puestos de trabajo, etiquetado como Discovering roles: Paralegal. Scoring roles muestra la lista de candidatos preseleccionados a medida que el evaluador la va procesando. Los lectores ven en qué punto se encuentra la ejecución y qué queda por hacer. Una barra de progreso implicaría una duración que la herramienta no puede conocer.
La espera que devuelve un identificador de tarea
Un barrido en tiempo real puede durar un minuto o más. En modo MCP, la llamada a la herramienta devuelve un estado de ejecución en lugar de esperar a que finalice todo el barrido. Esto mantiene la llamada dentro del tiempo de espera del cliente e indica al autor de la llamada que el trabajo continúa.
run_sweep espera 45 segundos por defecto. wait_seconds establece esa espera, limitada entre 0 y 600, y SWEEPY_MCP_WAIT_SECONDS reduce el límite máximo en los hosts con restricciones más estrictas. El estado de ejecución incluye un job_id, un objeto progress, un valor elapsed_seconds y un message:
{
"status": "ok",
"sweep_status": "running",
"job_id": "<job id>",
"progress": { "step": 3, "total": 5, "label": "Validating URLs" },
"elapsed_seconds": 41.2,
"debug_log": "<path>",
"message": "The sweep is still running. Call get_sweep_status to wait for it, then continue with get_jobs."
}
El cliente consulta get_sweep_status con el job_id hasta que sweep_status indique "completed". Sweepy sigue trabajando durante el traspaso, independientemente de si el cliente permanece conectado. La copia debe completarse dentro del tiempo de espera y leerse correctamente para un cliente que se vuelva a conectar más tarde. Se trata de un estado de ejecución que informa del progreso.
Los 45 segundos son un valor predeterminado del producto, establecido por _DEFAULT_WAIT_SECONDS y limitado por _MAX_WAIT_SECONDS. progress y elapsed_seconds cambian en cada ejecución, al igual que debug_log. El message indica la siguiente llamada a la herramienta en lugar de repetir números que el usuario ya conoce.
No hay dónde ocultar una copia deficiente
La interfaz se basa únicamente en texto, y el marco recorta cualquier elemento que se alargue demasiado. Una etiqueta debe ser autónoma, ya que no hay nada más en pantalla que la explique. Los mensajes de estado indican dónde se encuentra el lector, sin ningún indicador de carga en el que apoyarse.
Se sigue la regla de nomenclatura. START SWEEP, LOAD PROFILE y BUILD PROFILE comienzan con la acción. Sus subtítulos la reiteran como el objetivo del lector, por lo que nadie necesita el concepto interno de «perfil» para saber qué viene a continuación. La etiqueta de puntuación aplica la misma regla a un número. KEYWORD OVERLAP indica el recuento determinista, y MATCH indica el juicio de un agente.
El ancho del marco recorta las cadenas largas
El terminal marca las reglas. El texto es la única capa que explica algo, y el marco recorta todo lo que se sale de su ancho. Un error debe indicar el problema y la solución en la misma cadena. El lector no puede salir de la línea para leer otra.
Las cadenas proporcionan su propio contexto. Could not parse salary %r. Enter a number like 65000, 65,000, or 65k. informa de lo que ha fallado y de lo que hay que escribir en su lugar, sustituyendo %r por la entrada rechazada. Current profile: none loaded / build one to start hace lo mismo en caso de que falte un perfil. Una interfaz gráfica de usuario podría mostrar la segunda mitad de cualquiera de las dos frases en una información sobre herramientas. Aquí, la línea incluye ambas mitades.
La etiqueta como única explicación
La etiqueta de puntuación indica quién ha introducido el número. La documentación lo explica claramente: «Una tarjeta MATCH refleja un juicio. Una tarjeta KEYWORD OVERLAP refleja palabras compartidas». En cada tarjeta aparece una etiqueta junto a una puntuación. El lector sabe de qué afirmación se trata antes de abrir la lista.
Cada palabra también indica al lector qué tipo de comparación ha generado la cifra. KEYWORD OVERLAP se refiere a dos documentos. MATCH se refiere a una persona y un puesto de trabajo. Un lector que espere que las dos cifras coincidan interpretará mal una de ellas.
La etiqueta hace referencia al autor, no a la interfaz. Un agente puede enviar un juicio sin porcentaje. Esa tarjeta seguirá indicando KEYWORD OVERLAP, porque fue el autor quien escribió ese número. La ruta de ejecución se encuentra fuera de la tarjeta. El nombre del archivo de informe identifica una ejecución de MCP con mcp, y el encabezado del registro muestra el método de ejecución.
La denominación de los mosaicos sigue la misma regla. BUILD PROFILE indica la acción, y su subtítulo, Set up your job search, omite el término interno para referirse al objetivo del lector. LOAD PROFILE dice Open a search you saved, lo que describe lo que hace el mosaico.
Lo que escribí y cómo lo revisé
Función: único redactor de las cadenas de texto del producto que cita este caso práctico. Redacté los subtítulos de Launchpad y las indicaciones del asistente, y posteriormente los mensajes de progreso y el texto de validación. Las etiquetas de procedencia de la puntuación y el message de traspaso de MCP que transmite un cliente fueron lo último en redactarse. Dirigí la compilación con Copilot y Gemini, siguiendo las directrices de los agentes a nivel de repositorio y un control de calidad de CI. Verifiqué las cadenas de texto literales del producto cotejándolas con el código fuente de Sweepy.
Calibrar la confianza y luego actuar
El lector debe calibrar la confianza antes de actuar en función de una puntuación y saber qué está haciendo el sistema mientras espera. La interfaz no puede explicar cómo Sweepy ha generado una cifra ni cuánto tiempo tarda un proceso. Las cadenas de etiquetas y estado lo explican con el menor número de palabras posible, de una forma que funciona sin recursos visuales.
Las quince indicaciones en orden
El asistente ejecuta quince pasos. Las quince indicaciones de nivel superior aparecen en orden, y las preguntas de sí o no se muestran como un selector de sí/no.
? What is your name?
>
? What job titles are you looking for?
(Separate multiple titles with a comma)
>
? Where do you want to work? (City, State):
>
? Do you want to see remote-only roles? (Y/n)
? Do you want to include hybrid roles? (Y/n)
? What is the path to your resume PDF?
>
? What is your minimum target salary? (Leave blank to skip):
>
? Which boards do you want to search? Pick from any engine; downloaded engines are labeled.
? Do you want to add custom platforms or ATS domains? (Y/n)
? Enter must-have skills or keywords to prioritize
(comma-separated, leave blank to extract from resume):
>
? What export formats do you want?
[x] PDF Report
[x] CSV Spreadsheet
[ ] JSON Data
? Add job-tracking columns to the CSV? (date applied, status, interview stage,
offer, follow-up date, contact, notes) (Y/n)
? Do you want to configure multiple resume tracks
(e.g. Tech Writer vs UX Writer)? (Y/n)
? Do you have a portfolio, writing samples, or case studies to submit
with applications? (Y/n)
? Enable debug logging? (Logs are saved under logs/ in the application
directory): (Y/n)