@roilab/crm-cli 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,157 +1,157 @@
1
- ---
2
- name: task-preflight
3
- description: Cómo interpretar la respuesta de `crm task preflight` antes de crear una tarea. Decisión rápida sobre duplicados, sobrecarga de dominio y profundización con datos de GSC/GA4 cuando hace falta. Cárgalo SÓLO si el envelope del preflight tiene `similarTasks` con score alto, `urlScopedTasks` no vacío, o vas a crear una tarea URL-scoped y dudas si ya existe.
4
- when_to_use: "el preflight devolvió Posible duplicado", "urlScopedTasks no vacío", "openTaskCounts alto", "necesito profundizar con GSC/GA4 antes de crear", "la URL ya tenía un task pero está en done"
5
- ---
6
-
7
- # Task preflight — interpretación
8
-
9
- `crm task preflight` se llama **antes** de cualquier `crm task create`. Este
10
- skill explica cómo leer la respuesta sin volver a leerse cli/SKILL.md (que ya
11
- te dijo el ritual). Cárgalo sólo si el envelope te deja en duda; en el 80% de
12
- los casos los `hints[]` ya te dicen qué hacer.
13
-
14
- ## Forma de la respuesta (recordatorio)
15
-
16
- ```jsonc
17
- {
18
- "ok": true,
19
- "data": {
20
- "similarTasks": [ { id, title, status, score, sameDomain, when } ],
21
- "recall": [ { type, id, when, score, snippet } ], // [] si no pasaste --url
22
- "recentChanges": [ { id, url, occurredAt, note, types[] } ],
23
- "urlScopedTasks": [ { id, title, status, when } ], // [] si no pasaste --url
24
- "recentBacklinks": [ { id, sourceUrl, targetUrl, status, anchorText, when } ],
25
- "openTaskCounts": { todo, doing, blocked, done } | null, // null si no pasaste --domain
26
- "suggestedSkills": [ { slug, name, description, kind, score } ], // playbooks de agencia que matchean el título (staff; [] para clientes)
27
- "hints": [ "Posible duplicado: ...", ... ],
28
- "meta": { title, url, domainId, sinceMs, limit }
29
- },
30
- "summary": "preflight: N similar · M recall · ..."
31
- }
32
- ```
33
-
34
- ## Árbol de decisión
35
-
36
- ```
37
- similarTasks[0].score >= 0.55
38
- ├── status ∈ {todo, doing, blocked}
39
- │ → COMENTA en la existente (`crm comment create --task <id>`).
40
- │ NO crees una nueva. Si tu trabajo es escope adicional, edita la
41
- │ descripción con `crm task update <id> --description`.
42
- │
43
- └── status == done
44
- → Pregunta: ¿es regresión?
45
- - Sí: crea NUEVA citando la cerrada con `#[Title](id)` en la
46
- descripción + `--kind decision` en un comentario explicando
47
- por qué se reabre.
48
- - No: es trabajo de seguimiento real → crea nueva con `#link`.
49
-
50
- similarTasks[0].score ∈ [0.45, 0.55) y sameDomain == true
51
- → Lectura rápida con `crm task get <id>`. Si el title coincide en >2/3
52
- tokens, trátalo como duplicado fuerte (rama de arriba). Si no, sigue.
53
-
54
- urlScopedTasks no vacío (sin importar similarTasks)
55
- → La URL YA tiene KPIs ligados. Tu nueva tarea probablemente debería
56
- enlazar a la misma propertyLink (mismo scope) en vez de duplicar la
57
- medición. Mira `crm task get <id>` para ver el `keyMetric` y reusa.
58
-
59
- openTaskCounts.todo + .doing + .blocked >= 8
60
- → Dominio sobrecargado. Si el humano no pidió explícitamente "más",
61
- responde con la cuenta y pregunta qué priorizar.
62
-
63
- recentChanges contiene tu URL en los últimos 30 días con tipo coincidente
64
- → Lo pediste pero ya se hizo. Lee el `note` y la lista de `types[]`. Si
65
- coincide, NO crees — informa al humano con un resumen de lo que ya cambió.
66
-
67
- Nada de lo de arriba aplica
68
- → Adelante con `crm task create`. Pasa `#[Title](id)` referenciando los
69
- `recall` o `urlScopedTasks` si son tangenciales pero útiles.
70
-
71
- suggestedSkills no vacío
72
- → Hay un playbook de agencia que cubre este tipo de tarea. Si
73
- suggestedSkills[0].score ≥ 0.5 (o aparece como hint "Skill recomendada"),
74
- CÁRGALO antes de ejecutar: `crm skill pull <slug>` y síguelo — no improvises
75
- el método. Es ortogonal al resto: aplica tanto si creas la tarea como si
76
- editas una existente. (Vacío siempre para llamadas de cliente.)
77
- ```
78
-
79
- ## Cuándo cargar datos vivos (después del preflight, no antes)
80
-
81
- Si decides crear pero tu propuesta de KPI no es obvia, **entonces** carga la
82
- vista en vivo — no antes:
83
-
84
- | Necesitas... | Comando | Coste |
85
- |---|---|---|
86
- | Clicks/impresiones/CTR/posición agregados del dominio | `crm domain metrics dom_xyz --start … --end …` | Tinybird, ~50ms, sin cuota |
87
- | Mismo, filtrado a una URL | `crm gsc query --property prop_X --dimension page --filters "page=<url>"` | live GSC + queryPageCache 6h, cuenta cuota GSC en miss |
88
- | Tráfico/conversiones por URL | `crm ga4 query --property prop_X --filters "pagePath=<url>"` | live GA4, cuenta cuota |
89
- | Backlinks/anchors actuales hacia la URL | `crm backlink list --domain dom_xyz --target-url <url>` | Convex, gratis |
90
-
91
- Regla: **el preflight es Convex puro (gratis). Tinybird es barato. GSC/GA4
92
- live cuestan cuota — sólo si hay decisión real que tomar.**
93
-
94
- ## Qué no pre-crawlees
95
-
96
- - **Nunca** lances Screaming Frog para entender una URL puntual. Si necesitas
97
- ver el HTML, usa `WebFetch` (1 GET, sin cuota). SF se justifica cuando la
98
- tarea es "audita el sitio entero", no antes de crear cada tarea.
99
- - **No corras `crm gsc query` para todas las páginas del dominio** sólo para
100
- "tener contexto". Eso quema cuota. Si necesitas un overview, ya tienes
101
- `crm domain metrics`.
102
-
103
- ## Anti-patrones
104
-
105
- - **Pasar `--title` con palabras de relleno** ("Hacer cosa en pricing").
106
- Hace que `similarTasks` traiga ruido y los `hints` no detecten duplicados.
107
- Usa el verbo + sustantivo + URL/sección como en la propia tarea final.
108
- - **Ignorar `hints` y mirar sólo `similarTasks`.** Los hints están escritos
109
- por el server con la lógica completa (recall + scoped + counts). Confía en
110
- ellos.
111
- - **Crear sin `--domain`.** Sin dominio, `openTaskCounts` queda en `null` y
112
- `recentChanges` se restringe a coincidencias por URL. El preflight pierde
113
- la mitad de su valor.
114
- - **Llamar `crm recall` después del preflight "por si acaso".** El preflight
115
- ya hace recall (con cap de 10 items en lugar de 50, pero suficiente). Sólo
116
- llama `crm recall` directamente si necesitas más profundidad histórica
117
- (ej. `--since-ms` mayor a 180 días).
118
-
119
- ## Ejemplo de decisión (no ejecutar — sólo lectura)
120
-
121
- ```bash
122
- $ crm task preflight \
123
- --title "Reescribir meta title /seo-tools" \
124
- --url https://example.com/seo-tools \
125
- --domain dom_abc \
126
- --jq .data
127
- ```
128
-
129
- ```jsonc
130
- {
131
- "similarTasks": [
132
- { "id": "tsk_x1", "title": "Optimizar meta title de /seo-tools",
133
- "status": "done", "score": 0.78, "sameDomain": true,
134
- "when": 1741..., "reviewRequired": false }
135
- ],
136
- "recall": [
137
- { "type": "change", "id": "che_a", "when": 1741..., "score": 0.92,
138
- "snippet": "meta_title: 'SEO Tools — guía 2026'" }
139
- ],
140
- "urlScopedTasks": [],
141
- "recentChanges": [
142
- { "id": "che_a", "url": ".../seo-tools", "occurredAt": "2026-04-12",
143
- "types": ["meta_title"], "note": "rev2" }
144
- ],
145
- "openTaskCounts": { "todo": 3, "doing": 1, "blocked": 0, "done": 14 },
146
- "hints": [
147
- "Posible duplicado: \"Optimizar meta title de /seo-tools\" (estado: done). Revísala con `crm task get tsk_x1` antes de crear."
148
- ]
149
- }
150
- ```
151
-
152
- Lectura: el meta title ya se reescribió hace 3 semanas (`change` con `score`
153
- muy alto y `recentChanges` confirma). La tarea original está en `done`. Si
154
- estás aquí porque el humano dijo "está mal otra vez", esto es regresión →
155
- crea nueva citando `#[Optimizar meta title de /seo-tools](tsk_x1)` y deja un
156
- `--kind decision` explicando qué falla del rev2. Si no, NO crees — comenta
157
- al humano la fecha del último cambio.
1
+ ---
2
+ name: task-preflight
3
+ description: Cómo interpretar la respuesta de `crm task preflight` antes de crear una tarea. Decisión rápida sobre duplicados, sobrecarga de dominio y profundización con datos de GSC/GA4 cuando hace falta. Cárgalo SÓLO si el envelope del preflight tiene `similarTasks` con score alto, `urlScopedTasks` no vacío, o vas a crear una tarea URL-scoped y dudas si ya existe.
4
+ when_to_use: "el preflight devolvió Posible duplicado", "urlScopedTasks no vacío", "openTaskCounts alto", "necesito profundizar con GSC/GA4 antes de crear", "la URL ya tenía un task pero está en done"
5
+ ---
6
+
7
+ # Task preflight — interpretación
8
+
9
+ `crm task preflight` se llama **antes** de cualquier `crm task create`. Este
10
+ skill explica cómo leer la respuesta sin volver a leerse cli/SKILL.md (que ya
11
+ te dijo el ritual). Cárgalo sólo si el envelope te deja en duda; en el 80% de
12
+ los casos los `hints[]` ya te dicen qué hacer.
13
+
14
+ ## Forma de la respuesta (recordatorio)
15
+
16
+ ```jsonc
17
+ {
18
+ "ok": true,
19
+ "data": {
20
+ "similarTasks": [ { id, title, status, score, sameDomain, when } ],
21
+ "recall": [ { type, id, when, score, snippet } ], // [] si no pasaste --url
22
+ "recentChanges": [ { id, url, occurredAt, note, types[] } ],
23
+ "urlScopedTasks": [ { id, title, status, when } ], // [] si no pasaste --url
24
+ "recentBacklinks": [ { id, sourceUrl, targetUrl, status, anchorText, when } ],
25
+ "openTaskCounts": { todo, doing, blocked, done } | null, // null si no pasaste --domain
26
+ "suggestedSkills": [ { slug, name, description, kind, score } ], // playbooks de agencia que matchean el título (staff; [] para clientes)
27
+ "hints": [ "Posible duplicado: ...", ... ],
28
+ "meta": { title, url, domainId, sinceMs, limit }
29
+ },
30
+ "summary": "preflight: N similar · M recall · ..."
31
+ }
32
+ ```
33
+
34
+ ## Árbol de decisión
35
+
36
+ ```
37
+ similarTasks[0].score >= 0.55
38
+ ├── status ∈ {todo, doing, blocked}
39
+ │ → COMENTA en la existente (`crm comment create --task <id>`).
40
+ │ NO crees una nueva. Si tu trabajo es escope adicional, edita la
41
+ │ descripción con `crm task update <id> --description`.
42
+ │
43
+ └── status == done
44
+ → Pregunta: ¿es regresión?
45
+ - Sí: crea NUEVA citando la cerrada con `#[Title](id)` en la
46
+ descripción + `--kind decision` en un comentario explicando
47
+ por qué se reabre.
48
+ - No: es trabajo de seguimiento real → crea nueva con `#link`.
49
+
50
+ similarTasks[0].score ∈ [0.45, 0.55) y sameDomain == true
51
+ → Lectura rápida con `crm task get <id>`. Si el title coincide en >2/3
52
+ tokens, trátalo como duplicado fuerte (rama de arriba). Si no, sigue.
53
+
54
+ urlScopedTasks no vacío (sin importar similarTasks)
55
+ → La URL YA tiene KPIs ligados. Tu nueva tarea probablemente debería
56
+ enlazar a la misma propertyLink (mismo scope) en vez de duplicar la
57
+ medición. Mira `crm task get <id>` para ver el `keyMetric` y reusa.
58
+
59
+ openTaskCounts.todo + .doing + .blocked >= 8
60
+ → Dominio sobrecargado. Si el humano no pidió explícitamente "más",
61
+ responde con la cuenta y pregunta qué priorizar.
62
+
63
+ recentChanges contiene tu URL en los últimos 30 días con tipo coincidente
64
+ → Lo pediste pero ya se hizo. Lee el `note` y la lista de `types[]`. Si
65
+ coincide, NO crees — informa al humano con un resumen de lo que ya cambió.
66
+
67
+ Nada de lo de arriba aplica
68
+ → Adelante con `crm task create`. Pasa `#[Title](id)` referenciando los
69
+ `recall` o `urlScopedTasks` si son tangenciales pero útiles.
70
+
71
+ suggestedSkills no vacío
72
+ → Hay un playbook de agencia que cubre este tipo de tarea. Si
73
+ suggestedSkills[0].score ≥ 0.5 (o aparece como hint "Skill recomendada"),
74
+ CÁRGALO antes de ejecutar: `crm skill pull <slug>` y síguelo — no improvises
75
+ el método. Es ortogonal al resto: aplica tanto si creas la tarea como si
76
+ editas una existente. (Vacío siempre para llamadas de cliente.)
77
+ ```
78
+
79
+ ## Cuándo cargar datos vivos (después del preflight, no antes)
80
+
81
+ Si decides crear pero tu propuesta de KPI no es obvia, **entonces** carga la
82
+ vista en vivo — no antes:
83
+
84
+ | Necesitas... | Comando | Coste |
85
+ |---|---|---|
86
+ | Clicks/impresiones/CTR/posición agregados del dominio | `crm domain metrics dom_xyz --start … --end …` | Tinybird, ~50ms, sin cuota |
87
+ | Mismo, filtrado a una URL | `crm gsc query --property prop_X --dimension page --filters "page=<url>"` | live GSC + queryPageCache 6h, cuenta cuota GSC en miss |
88
+ | Tráfico/conversiones por URL | `crm ga4 query --property prop_X --filters "pagePath=<url>"` | live GA4, cuenta cuota |
89
+ | Backlinks/anchors actuales hacia la URL | `crm backlink list --domain dom_xyz --target-url <url>` | Convex, gratis |
90
+
91
+ Regla: **el preflight es Convex puro (gratis). Tinybird es barato. GSC/GA4
92
+ live cuestan cuota — sólo si hay decisión real que tomar.**
93
+
94
+ ## Qué no pre-crawlees
95
+
96
+ - **Nunca** lances Screaming Frog para entender una URL puntual. Si necesitas
97
+ ver el HTML, usa `WebFetch` (1 GET, sin cuota). SF se justifica cuando la
98
+ tarea es "audita el sitio entero", no antes de crear cada tarea.
99
+ - **No corras `crm gsc query` para todas las páginas del dominio** sólo para
100
+ "tener contexto". Eso quema cuota. Si necesitas un overview, ya tienes
101
+ `crm domain metrics`.
102
+
103
+ ## Anti-patrones
104
+
105
+ - **Pasar `--title` con palabras de relleno** ("Hacer cosa en pricing").
106
+ Hace que `similarTasks` traiga ruido y los `hints` no detecten duplicados.
107
+ Usa el verbo + sustantivo + URL/sección como en la propia tarea final.
108
+ - **Ignorar `hints` y mirar sólo `similarTasks`.** Los hints están escritos
109
+ por el server con la lógica completa (recall + scoped + counts). Confía en
110
+ ellos.
111
+ - **Crear sin `--domain`.** Sin dominio, `openTaskCounts` queda en `null` y
112
+ `recentChanges` se restringe a coincidencias por URL. El preflight pierde
113
+ la mitad de su valor.
114
+ - **Llamar `crm recall` después del preflight "por si acaso".** El preflight
115
+ ya hace recall (con cap de 10 items en lugar de 50, pero suficiente). Sólo
116
+ llama `crm recall` directamente si necesitas más profundidad histórica
117
+ (ej. `--since-ms` mayor a 180 días).
118
+
119
+ ## Ejemplo de decisión (no ejecutar — sólo lectura)
120
+
121
+ ```bash
122
+ $ crm task preflight \
123
+ --title "Reescribir meta title /seo-tools" \
124
+ --url https://example.com/seo-tools \
125
+ --domain dom_abc \
126
+ --jq .data
127
+ ```
128
+
129
+ ```jsonc
130
+ {
131
+ "similarTasks": [
132
+ { "id": "tsk_x1", "title": "Optimizar meta title de /seo-tools",
133
+ "status": "done", "score": 0.78, "sameDomain": true,
134
+ "when": 1741..., "reviewRequired": false }
135
+ ],
136
+ "recall": [
137
+ { "type": "change", "id": "che_a", "when": 1741..., "score": 0.92,
138
+ "snippet": "meta_title: 'SEO Tools — guía 2026'" }
139
+ ],
140
+ "urlScopedTasks": [],
141
+ "recentChanges": [
142
+ { "id": "che_a", "url": ".../seo-tools", "occurredAt": "2026-04-12",
143
+ "types": ["meta_title"], "note": "rev2" }
144
+ ],
145
+ "openTaskCounts": { "todo": 3, "doing": 1, "blocked": 0, "done": 14 },
146
+ "hints": [
147
+ "Posible duplicado: \"Optimizar meta title de /seo-tools\" (estado: done). Revísala con `crm task get tsk_x1` antes de crear."
148
+ ]
149
+ }
150
+ ```
151
+
152
+ Lectura: el meta title ya se reescribió hace 3 semanas (`change` con `score`
153
+ muy alto y `recentChanges` confirma). La tarea original está en `done`. Si
154
+ estás aquí porque el humano dijo "está mal otra vez", esto es regresión →
155
+ crea nueva citando `#[Optimizar meta title de /seo-tools](tsk_x1)` y deja un
156
+ `--kind decision` explicando qué falla del rev2. Si no, NO crees — comenta
157
+ al humano la fecha del último cambio.
@@ -1,8 +1,8 @@
1
- ---
2
- name: whitespark-tool
3
- description: When the user wants citation gap analysis, managed citation building, review generation campaigns, or local rank tracking. Trigger on "Whitespark," "citation finder," "where are my competitors listed," "citation gap," "build citations," "review generation tool," or "get more reviews." Note that Whitespark does NOT have an MCP server — it's dashboard-driven with limited API.
4
- ---
5
-
1
+ ---
2
+ name: whitespark-tool
3
+ description: When the user wants citation gap analysis, managed citation building, review generation campaigns, or local rank tracking. Trigger on "Whitespark," "citation finder," "where are my competitors listed," "citation gap," "build citations," "review generation tool," or "get more reviews." Note that Whitespark does NOT have an MCP server — it's dashboard-driven with limited API.
4
+ ---
5
+
6
6
  # Whitespark Tool
7
7
 
8
8
  > **Note:** LocalSEOData (`localseodata-tool`) now covers citation audits via `citation_audit`. Use LocalSEOData as default for citation data. Whitespark remains the preferred tool for citation building and review generation campaigns (Reputation Builder).