@numericoach/gskills-admin-cli 0.1.7 → 0.1.9

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,114 +1,154 @@
1
1
  ---
2
2
  name: gskills-content-sync-cache-ops
3
- description: Use when operating GSkills content through DB/CLI: pages, quizzes, learning paths, content news, content assistant outputs, sync diffs/runs, deploy cache resets, menu translation cache issues, or stale content checks.
3
+ description: Use when Codex is asked to maintain GSkills content data outside normal dev work: sync drift diagnosis, page visibility bugs, cache invalidation, page metadata backfills, content assistant lookups, content-news checks, or admin ingest repair.
4
4
  ---
5
5
 
6
- # GSkills Content, Sync, And Cache Ops
6
+ # GSkills Content, Sync, Cache Ops
7
7
 
8
- Use this skill for non-code GSkills content operations that depend on prod data.
8
+ Use this for Codex-backed maintenance of GSkills content data.
9
9
 
10
- This covers the work behind global pages/quizzes, Air Liquide content-news, content assistant outputs, sync checks, and cache resets.
10
+ This is not about UI visits. It is about proving and fixing content state with DB, sync logs, cache helpers, and production verification.
11
11
 
12
- ## Evidence Baseline
12
+ ## What Codex Has Actually Been Used For
13
13
 
14
- Checked on 2026-05-13 over roughly the last 120 days:
14
+ - Investigating a Google Contacts page sync issue where source global content was published but client copies stayed disabled.
15
+ - Proving stale deploy cache after sync/direct data repair and invalidating the right page/menu/app scopes.
16
+ - Repairing incomplete admin ingest syncs for `global` with the production repair workflow.
17
+ - Backfilling `Pages.headerColor` from global pages to client copies across 49,338 mapped pages.
18
+ - Comparing broken and working synced instances when a quiz exists in editor content but does not render on deploy.
19
+ - Finding content-assistant artifacts from `Chat` and `ChatMessage` metadata.
20
+ - Using Gmail/docs/source material to understand webinar/resource ingestion before writing GSkills data.
15
21
 
16
- - Theo/coach2 visited page list/edit routes 180 times.
17
- - `coach2@numericoach.fr` wrote 43 global page updates and 7 quiz updates.
18
- - Theo visited `/fr/admin/content-news` 83 times, all on Air Liquide in the recent sample.
19
- - Theo visited settings 47 times, project data 44 times, and content assistant detail pages repeatedly.
20
- - Chronicle shows repeated GSkills content admin, EditorJS JSON, Content Assistant, content-news, and Air Liquide cache/translation validation work.
21
- - Air Liquide menu/cache translation work showed the failure mode: DB translation and cached deploy menu can drift, so compare source data, runtime loader, and cache invalidation.
22
+ ## Sync Drift Investigation
22
23
 
23
- ## Rules
24
+ Use this when a synced page/resource/quiz/path looks different on clients.
24
25
 
25
- 1. Prefer `gskills-admin` CLI for content reads, sync, and cache invalidation.
26
- 2. Use DB reads to prove current state and history.
27
- 3. Use raw DB writes only for deliberate data repair, and only with a matching admin log.
28
- 4. Never assume global content is deployed to a client. Check sync state or compare source ids.
29
- 5. For cache issues, prove whether data is wrong or cache is stale before invalidating everything.
26
+ 1. Identify source global row and target instance rows.
27
+ 2. Query target copies by source linkage, not slug only.
28
+ - For pages, prefer `crossInstanceID` when relevant.
29
+ 3. Compare:
30
+ - `disabled`
31
+ - `archived`
32
+ - title/slug/language
33
+ - `headerColor`
34
+ - category/app links
35
+ - embedded quiz ids
36
+ - relation tables
37
+ 4. Check sync logs and admin logs around the event.
38
+ 5. Inspect the sync engine only after prod data proves the drift.
39
+ 6. Separate code fix from prod data repair.
30
40
 
31
- ## Read Content State
41
+ Known example:
32
42
 
33
- Useful CLI reads:
43
+ - Google Contacts page source was `disabled=false`, target copies were still `disabled=true`.
44
+ - The sync rule preserved target disabled state through `resolveSyncedDisabled`.
45
+ - Admin logs showed manual `pages.toggle-disabled` after the sync.
34
46
 
35
- ```bash
36
- gskills-admin pages list --where '{"language":"fr","slug":{"contains":"gemini"}}' --fields id,name,slug,language,instanceId,disabled --output json
37
- gskills-admin quizzes list --where '{"language":"fr"}' --fields id,name,language,instanceId --output json
38
- gskills-admin learning-paths list --instance global --output json
39
- gskills-admin menus list --instance global --output json
40
- ```
47
+ ## Cache Invalidation After Data Repair
41
48
 
42
- Useful DB checks:
49
+ Use this when a direct DB fix or sync leaves old deploy data visible.
43
50
 
44
- - current page or quiz row,
45
- - translations via parent/root/source ids,
46
- - last `LogsUser` entries for the entity,
47
- - client copy by `sourcePageId`, `sourceQuizId`, or equivalent source field,
48
- - menu item pointing to the page,
49
- - deploy cache version rows or settings.
51
+ Rules:
50
52
 
51
- ## Sync Runbook
53
+ - Identify the edited entity first.
54
+ - Invalidate scopes for the entity, not only the visible symptom.
55
+ - If a `Pages` field changed, invalidate page scopes and menu/app scopes when the page appears in menus or app lists.
52
56
 
53
- Before pushing global content to a client:
57
+ Known page repair scopes:
54
58
 
55
- 1. Identify source global items.
56
- 2. Identify target instance.
57
- 3. Run a diff.
59
+ - `pages`
60
+ - `pages-count`
61
+ - `pages-lite`
62
+ - `page-minimal`
63
+ - `pages-knowledge`
64
+ - `deploy-home-static`
65
+ - `applications`
66
+ - `menu-bundle`
58
67
 
59
- ```bash
60
- gskills-admin sync diff --target <instanceId> --preset client-content --output json
61
- gskills-admin sync diff --target <instanceId> --preset pages-only --pages <pageId,pageId> --output json
62
- ```
68
+ Use version bumps from:
63
69
 
64
- 4. Check whether the diff includes only the intended items.
65
- 5. Apply with `--yes` only after a clean diff.
70
+ - `src/lib/deploy-cache.ts`
71
+ - `src/lib/sync-engine/cache-invalidation.ts`
66
72
 
67
- ```bash
68
- gskills-admin sync run --target <instanceId> --preset pages-only --pages <pageId,pageId> --yes --output json
69
- ```
73
+ Verify current cache keys disappear or versions increase for sample instances.
74
+
75
+ ## Page Metadata Backfill
76
+
77
+ Use this for scoped prod backfills like `Pages.headerColor`.
78
+
79
+ Pattern:
80
+
81
+ 1. Count mapped rows.
82
+ 2. Count mismatches before.
83
+ 3. Write only the intended column.
84
+ 4. Count mismatches after.
85
+ 5. Tell the user the exact write scope.
86
+
87
+ Known validated shape:
70
88
 
71
- 6. Reset cache narrowly.
89
+ - `UPDATE "Pages" SET "headerColor" = global_page."headerColor"` only.
90
+ - Target rows where `crossInstanceID` points to global page.
91
+ - Before: 49,338 mapped pages, 25,611 mismatches.
92
+ - After: 0 mismatches.
93
+
94
+ ## Admin Ingest Repair
95
+
96
+ Use this when the UI says synchronisations incomplètes or admin console data has repair tasks.
97
+
98
+ Preferred path:
72
99
 
73
100
  ```bash
74
- gskills-admin cache invalidate --instance <instanceId> --scope pages --languages fr,en --dry-run --output json
75
- gskills-admin cache invalidate --instance <instanceId> --scope pages --languages fr,en --yes --output json
101
+ bunx vercel env pull /tmp/gskills-prod.env --environment=production --yes
102
+ bun --conditions react-server -e 'import { getAdminIngestRepairState } from "./src/lib/admin-ingest/repair"; ...'
76
103
  ```
77
104
 
78
- ## Cache And Translation Bugs
105
+ Then run the existing repair workflow, not ad hoc writes:
106
+
107
+ - `getAdminIngestRepairState(instanceId)`
108
+ - `adminIngestRepairWorkflow(instanceId, { maxConcurrentDays: 1 })`
109
+
110
+ Verify the queue is empty:
111
+
112
+ - `canLaunch=false`
113
+ - `blockedReason="no_repairs_needed"`
114
+ - `affectedDayCount=0`
115
+ - `repairTargetCount=0`
79
116
 
80
- When the user says a menu, page title, card, or learning path label shows the wrong language:
117
+ ## Content Assistant Lookup
81
118
 
82
- 1. Capture the exact instance, language, route, and label.
83
- 2. Query source rows and translated target rows.
84
- 3. Query menu items and learning path items that display the label.
85
- 4. Inspect last admin logs touching that entity.
86
- 5. Check cache invalidation scope.
87
- 6. Simulate the runtime loader when possible.
88
- 7. Invalidate only the relevant scope:
89
- - `pages`
90
- - `pages-knowledge`
91
- - `menu-bundle`
92
- - `applications`
93
- - `all` only when the broken surface spans multiple bundles.
119
+ Use this when the user asks for “the artifact” or a content creation thread.
120
+
121
+ Query:
122
+
123
+ - `User`
124
+ - `Chat`
125
+ - `ChatMessage`
126
+ - `metadata.artifact`
127
+ - `CHAT_KINDS.CONTENT_ASSISTANT`
128
+
129
+ Return the exact prod route:
130
+
131
+ ```text
132
+ https://g-skills.fr/fr/super-admin/global/content-assistant/<chatId>
133
+ ```
94
134
 
95
- ## Content Assistant And Content News
135
+ Do not browse manually when the artifact text and metadata are in DB.
96
136
 
97
- For content assistant/content-news work:
137
+ ## Broken Deploy Content After Sync
98
138
 
99
- - Check the generated draft record and destination type.
100
- - Confirm whether the content is a page, internal knowledge, content news item, or source material.
101
- - Keep EditorJS JSON intact. Use structured JSON parsing, not regex surgery.
102
- - Check image/topic enrichment from the existing helpers before inventing a new content path.
103
- - After creating content, verify the destination row and any linked page/menu/category records.
139
+ Use this when a thing exists in editor but not on the deploy page.
104
140
 
105
- ## Evidence To Return
141
+ - Compare the broken instance against a synced working instance.
142
+ - Query embedded ids from EditorJS JSON.
143
+ - Query relation tables separately.
144
+ - Pull production logs when runtime behavior matters.
145
+ - Keep the root cause tentative until the loader/action that returns empty/null is proven.
106
146
 
107
- Return:
147
+ Good proof:
108
148
 
109
- - source item ids,
110
- - target instance ids,
111
- - diff summary,
112
- - cache scope invalidated,
113
- - last admin log touching the item,
114
- - any remaining deploy/cache uncertainty.
149
+ - broken page id,
150
+ - working page id,
151
+ - embedded quiz/resource id,
152
+ - relation count,
153
+ - runtime logs,
154
+ - exact API call or loader result.
@@ -0,0 +1,180 @@
1
+ ---
2
+ name: gskills-customer-playbooks
3
+ description: Use when a GSkills task names a recurring customer and the agent needs operational memory about that customer, common requests, likely checks, sync patterns, access quirks, or communication sources.
4
+ ---
5
+
6
+ # GSkills Customer Playbooks
7
+
8
+ Use this skill when the user names a recurring GSkills customer. This is operational memory, not live proof. If the answer or action matters in production, re-check current DB rows, admin logs, sync logs, Slack, Gmail, Google Chat, or the app before acting.
9
+
10
+ ## General Defaults
11
+
12
+ - Start from the customer instance, not from a generic global theory.
13
+ - For broken syncs, compare the target instance against global and against a working synced sibling when useful.
14
+ - For feedbacks, inspect the feedback row, user, instance, and admin logs before explaining the cause.
15
+ - For access issues, check user instance, access passes, auth mode, domain or account allowlists, then logs.
16
+ - For client wording, use the real thread or channel when available.
17
+ - Use `gskills-vocabulary` before writing human-facing summaries.
18
+
19
+ ## Air Liquide
20
+
21
+ Air Liquide is the heavy recurring customer. Expect large content volume, customized content, language constraints, and auth or Google Admin setup work.
22
+
23
+ Common work:
24
+
25
+ - Broad content synchronisation from global, often with thousands of items.
26
+ - Large diffs with many `SKIPPED_CUSTOMIZED` items. This is normal, not automatically a failure.
27
+ - Page, quiz, parcours, menu, resource, badge, and internal knowledge parity checks after sync.
28
+ - Feedback instance attribution and page-family parity repairs.
29
+ - Access-denied work around expired access passes or domain allowlists.
30
+ - Okta setup and auth callback checks.
31
+ - Google Admin users, groups, and OU checks. Users and groups have worked before while OU access required scope/config follow-up.
32
+ - Locale and wording work, especially Quebec French.
33
+ - Short natural client-facing email drafts from the actual thread.
34
+
35
+ Known context:
36
+
37
+ - Customer id used during Google Admin checks: `C028v0b9g`.
38
+ - Known Google Chat space: `Air Liquide x Numericoach - GSkills`, `spaces/AAQAc2CT1qI`.
39
+ - Harold OUSSET was a known user whose display name required surname-first parsing.
40
+ - Air Liquide syncs should usually start with `sync logs`, then `sync diff`, then a narrow or preset run.
41
+
42
+ ## HASAP
43
+
44
+ HASAP often appears in feedback and content visibility work.
45
+
46
+ Common work:
47
+
48
+ - Webinar content, parcours updates, invitations, user imports, and client-side launch follow-up.
49
+ - Badge visibility and badge delivery repairs.
50
+ - Google Forms badge issues where the page trigger stayed the same but the badge target changed.
51
+ - Quiz completion and answer submission investigations.
52
+ - Page sync visibility issues where disabled or archived state and sync logs mattered.
53
+
54
+ Known context:
55
+
56
+ - Known Google Chat space: `GSkills_Hasap_x_Numericoach`, `spaces/AAQAxJEETeI`.
57
+ - The recurring badge pitfall is workflow deduplication. A same-page `QUIZ_COMPLETED` execution can block a new badge action if only the badge target changed.
58
+ - Do not explain HASAP sync issues from the URL alone. Use prod data, the exact sync run, `LogsUser`, and the page or parcours family.
59
+
60
+ ## FM LOGISTIC Google & Co
61
+
62
+ FM Logistic work is usually about resources, webinars, and visibility rules.
63
+
64
+ Known fixed facts:
65
+
66
+ - Instance name: `FM LOGISTIC Google & Co`.
67
+ - Instance id: `cmgtgrz02000t04l501wbp459`.
68
+ - Instance slug: `fm-logistic`.
69
+ - Main language: `fr`.
70
+
71
+ Common work:
72
+
73
+ - Add or audit webinar replays.
74
+ - Upload Drive recordings to GCS-backed GSkills resources.
75
+ - Keep AI webinars restricted to the right audience.
76
+ - Verify the end-user webinar page and custom video player.
77
+
78
+ Important rule:
79
+
80
+ - AI webinars should keep the French `IA` application/category attached.
81
+ - FM has a manual group named `Groupe AVEC IA` with inverted visibility. Do not add a broad active application like Google Workspace unless the user explicitly wants broader access.
82
+
83
+ Use the `fm-logistic-webinar-ingestion` skill for detailed webinar work.
84
+
85
+ ## LGCF
86
+
87
+ LGCF often appears in technical rollout, Google Group access, feedback, and success-story work.
88
+
89
+ Common work:
90
+
91
+ - Google Chat and Gmail context checks before drafting client replies.
92
+ - Security group or Google Group behavior.
93
+ - Progression quiz feedback.
94
+ - Leaderboard and adjusted-points investigations, especially when unavailable quiz history changes visible ranking.
95
+ - Success-story outreach drafts.
96
+
97
+ Known context:
98
+
99
+ - Known Google Chat space: `LGCF & Numericoach | GSkills Technique IT`, `spaces/AAQACgXH1kQ`.
100
+ - A known feedback case involved leaderboard ordering versus raw points. Verify whether the complaint is raw progress, visible ranking, adjusted points, or course activity before digging.
101
+
102
+ ## V&B
103
+
104
+ V&B has appeared in feedback triage around evaluation quiz behavior.
105
+
106
+ Common work:
107
+
108
+ - Quiz or evaluation feedback checks.
109
+ - Treat as a feedback-backed investigation. Verify the exact feedback row and current quiz state before describing the issue.
110
+
111
+ ## Seine Yonne
112
+
113
+ Seine Yonne has appeared in access/login diagnosis.
114
+
115
+ Common work:
116
+
117
+ - Granular account allowlist checks.
118
+ - Login denial troubleshooting.
119
+
120
+ Known context:
121
+
122
+ - One prior issue was that `dmoindrot@farmidable.fr` was not in `accountGranular`, while `dmoindrot@seineyonne.fr` was.
123
+ - Do not collapse similar emails into one access story.
124
+
125
+ ## Euromaster
126
+
127
+ Euromaster has appeared in sync and broad repair work.
128
+
129
+ Common work:
130
+
131
+ - Page-only or pages plus parcours synchronisation.
132
+ - Post-sync verification.
133
+ - Data repair blast-radius checks.
134
+
135
+ ## Commune de Divonne-les-Bains, AS de Pic, 360 Courtage
136
+
137
+ These have appeared as new-client style pushes.
138
+
139
+ Common work:
140
+
141
+ - Broad first synchronisation from global.
142
+ - High created counts are expected.
143
+ - Run `client-content` diff first, then apply, then verify menus and deploy cache.
144
+
145
+ ## Nickel Banque
146
+
147
+ Nickel Banque has appeared in feedback instance selection and page-family parity context.
148
+
149
+ Common work:
150
+
151
+ - Feedback routing or instance attribution checks.
152
+ - Verify the actual route context, target instance, and content family before repairing.
153
+
154
+ ## Terega
155
+
156
+ Terega has appeared as a one-off client synchronisation target.
157
+
158
+ Common work:
159
+
160
+ - Treat as normal client-content sync unless the live logs say otherwise.
161
+ - Resolve the instance id and check recent sync logs before applying.
162
+
163
+ ## Euralis, Orqual, Groupe Kiosque, UTT Yarns
164
+
165
+ These have appeared in broad data repair blast-radius checks.
166
+
167
+ Common work:
168
+
169
+ - Verify current state before touching anything.
170
+ - Do not infer a recurring product rule only because they were touched by a previous multi-instance repair.
171
+
172
+ ## Instance Mere And Global
173
+
174
+ Global is the source of truth for shared content.
175
+
176
+ Common work:
177
+
178
+ - Create or update global courses, tutorials, granules, modules, quizzes, parcours, badges, menus, resources, and base de connaissance content.
179
+ - Compare global to a client instance before sync.
180
+ - Keep client customizations intact unless the user explicitly wants to overwrite or repair them.
@@ -1,129 +1,126 @@
1
1
  ---
2
2
  name: gskills-feedback-db-ops
3
- description: Use when doing recurring GSkills feedback operations from prod data: triage, assign, categorize, resolve, bulk stale pending-validation cleanup, reply email checks, or auditing feedback admin logs.
3
+ description: Use when Codex is asked to handle GSkills feedback as an operational DB-backed workflow: investigate from prod rows, import feedback from emails, triage with Slack/Marina context, repair user state, close tickets, assign Theo, or send reply emails.
4
4
  ---
5
5
 
6
6
  # GSkills Feedback DB Ops
7
7
 
8
- Use this skill for feedback work that is operational and data-heavy.
9
-
10
- For deep root-cause investigations, also use `$gskills-feedback-resolving`. This skill focuses on the repeated admin ops Theo actually does.
11
-
12
- ## Evidence Baseline
13
-
14
- Checked on 2026-05-13 over roughly the last 120 days:
15
-
16
- - Theo visited feedback list/detail pages 196 times.
17
- - Theo changed feedback status 45 times.
18
- - Theo assigned feedbacks 29 times.
19
- - Theo bulk-resolved stale pending-validation feedbacks 29 times.
20
- - Theo changed feedback categories 10 times.
21
- - Feedback reply sends are fewer but high-risk because they email real users.
22
- - Recent DB reply bodies are all multi-line, so `send-reply` must use `--body-file`.
23
-
24
- ## Rules
25
-
26
- 1. Start from prod DB data, not the AI summary.
27
- 2. Read the feedback row, user, instance, URL, screenshot fields, category, status, assignee, and admin logs before changing anything.
28
- 3. For customer-visible email, preserve the language of the feedback or user UI.
29
- 4. Use the authenticated CLI or existing server action path for writes when available.
30
- 5. Never raw-update feedback status without logging the admin event shape.
31
- 6. Bulk cleanup needs a dry-run list and a cutoff reason.
32
-
33
- ## Read The Ticket
34
-
35
- Use this shape first:
36
-
37
- ```bash
38
- bun - <<'EOF'
39
- import { db } from "./src/lib/db"
40
-
41
- const feedbackId = process.argv[2]
42
- const feedback = await db.feedback.findUnique({
43
- where: { id: feedbackId },
44
- include: {
45
- user: { select: { id: true, email: true, name: true, language: true, instanceID: true } },
46
- instance: { select: { id: true, name: true, URL: true } },
47
- assignedTo: { select: { id: true, email: true, name: true } },
48
- replies: { orderBy: { createdAt: "desc" }, take: 5 },
49
- },
50
- })
51
-
52
- const logs = await db.logsUser.findMany({
53
- where: { entityType: "feedback", entityId: feedbackId },
54
- orderBy: { createdAt: "desc" },
55
- take: 20,
56
- select: { createdAt: true, userEmail: true, typeLog: true, slug: true, detailLog: true, metadata: true },
57
- })
58
-
59
- console.log(JSON.stringify({ feedback, logs }, null, 2))
60
- await db.$disconnect()
61
- EOF
62
- ```
63
-
64
- ## Common Operations
65
-
66
- ### Assign Or Reassign
67
-
68
- - Confirm the feedback exists.
69
- - Confirm the assignee user id.
70
- - Check if there is already an assignee.
71
- - Prefer the CLI/API flow if available.
72
- - If doing a DB repair, create a matching `LogsUser` entry with `slug = "feedback.assignee.assign"` or `feedback.assignee.unassign`.
73
-
74
- ### Categorize
75
-
76
- - Read current category and AI category.
77
- - Use the human category as the source of truth after review.
78
- - Log with `feedback.category.update`.
79
- - Do not categorize from the title only. Read screenshot and URL.
80
-
81
- ### Resolve
82
-
83
- - Resolve only after root cause or expected behavior is clear.
84
- - If a reply email is needed, use:
8
+ Use this for recurring Codex feedback work, not generic UI ticket browsing.
9
+
10
+ The pattern is: source evidence -> prod DB row -> root cause or data repair -> optional code fix -> feedback state/email update.
11
+
12
+ ## What Codex Has Actually Been Used For
13
+
14
+ - Building the feedback resolving skill after mining past Codex sessions and prod schema.
15
+ - Checking recent GSkills tickets with `#g-skills-auto`, prioritizing Marina’s human comments over automatic AI comments.
16
+ - Importing forwarded Gmail issues into prod `Feedback`, `FeedbackAnalysis`, and `FeedbackAssignee`.
17
+ - Investigating a course completion bug from a feedback URL, proving `UserPath.isAchieved = false` despite passed quiz attempts, then applying the prod completion write.
18
+ - Closing feedback after prod deploy verification, assigning it to Theo, creating a `FeedbackReply`, and sending a customer email.
19
+ - Categorizing and resolving stale tickets when the root cause is known.
20
+
21
+ ## Default Workflow
22
+
23
+ 1. Read the source.
24
+ - Feedback URL or id.
25
+ - Slack `#g-skills-auto` thread, especially Marina replies.
26
+ - Gmail thread when the ticket comes from forwarded client mail.
27
+ - Screenshot and client metadata.
28
+ 2. Read prod DB.
29
+ - `Feedback`
30
+ - `FeedbackAnalysis`
31
+ - `CommentFeedback`
32
+ - `FeedbackAssignee`
33
+ - `FeedbackReply`
34
+ - affected `User`, `Instance`, `Pages`, quiz/progress/access rows when relevant.
35
+ 3. Prove the issue.
36
+ - For content/access bugs, simulate the affected runtime path.
37
+ - For quiz/progress bugs, compare attempts with `UserPath` and learning-path completion rows.
38
+ - For imported emails, split separate asks into separate feedbacks.
39
+ 4. Act.
40
+ - Use existing app/CLI action when available.
41
+ - If a direct DB write is requested and safe, write the minimal rows and verify.
42
+ - For customer replies, use file-based body text and preserve the customer/user language.
43
+ 5. Verify.
44
+ - Re-read feedback state.
45
+ - Confirm assignee, status, reply row, email id, and admin log where applicable.
46
+
47
+ ## Email-To-Feedback Import
48
+
49
+ Use this when the user says a client email should become GSkills feedback.
50
+
51
+ Rules:
52
+
53
+ - Search both Theo and developer mailboxes when the user mentions both.
54
+ - Resolve the real Gmail API thread id with `gws`, not the UI fragment.
55
+ - Read the full thread.
56
+ - One email can contain multiple tickets. Split them.
57
+ - If the issue already exists, add context to the existing feedback instead of duplicating.
58
+ - Insert enough context for the feedback detail screen to be useful.
59
+
60
+ Tables:
61
+
62
+ - `Feedback`
63
+ - `FeedbackAnalysis`
64
+ - `FeedbackAssignee`
65
+ - optional `CommentFeedback`
66
+
67
+ Verification:
68
+
69
+ - feedback ids,
70
+ - instance and user pairing,
71
+ - `status = ANALYZED` when imported as actionable,
72
+ - assignee is Theo when requested,
73
+ - original thread ids preserved in context.
74
+
75
+ ## Feedback Closure With Email
76
+
77
+ Use this when the user asks to treat a feedback after a prod fix.
78
+
79
+ 1. Confirm production deployment is live when the fix depends on deploy.
80
+ 2. Re-run the affected-user proof or live state check.
81
+ 3. Draft in the same language as the user/feedback.
82
+ 4. Send with the CLI:
85
83
 
86
84
  ```bash
87
85
  gskills-admin feedback send-reply <feedbackId> --subject "..." --body-file ./reply.txt --dry-run --output json
88
86
  gskills-admin feedback send-reply <feedbackId> --subject "..." --body-file ./reply.txt --yes --output json
89
87
  ```
90
88
 
91
- - Real email body must be file-based.
92
- - After email send, verify `FeedbackReply`, `repliedAt`, `repliedById`, status, and `feedback.email.sent` or `feedback.resolve.with-email` log.
89
+ 5. Verify:
90
+ - `Feedback.status`
91
+ - `FeedbackAssignee`
92
+ - `FeedbackReply`
93
+ - `repliedAt`
94
+ - email message id
93
95
 
94
- ### Bulk Resolve Stale Pending Validation
96
+ ## Progress Or Course Completion Repair
95
97
 
96
- This is the pattern behind `feedback.status.bulk-resolve-stale-validation`.
98
+ Use this when a user passed a quiz but a page/course/path did not validate.
97
99
 
98
- Dry-run first:
100
+ Proof chain:
99
101
 
100
- - query all `PENDING_VALIDATION` rows older than the cutoff,
101
- - exclude recently updated rows,
102
- - group by instance and category,
103
- - print ids, user emails, titles, updatedAt, and last admin log,
104
- - ask whether the cutoff is intentional if not supplied by the user.
102
+ - feedback row,
103
+ - user id,
104
+ - page id,
105
+ - quiz id,
106
+ - quiz attempts with `passed=true`,
107
+ - `UserPath.isAchieved`,
108
+ - learning-path item completion rows,
109
+ - relevant runtime function.
105
110
 
106
- Apply only when the user asked for the cleanup:
111
+ For embedded quiz completion, the known safe dry-run/write path is:
107
112
 
108
- - set status to `RESOLVED`,
109
- - set `treatedAt` if the app expects it,
110
- - keep `repliedAt` untouched,
111
- - create one admin log per feedback with metadata:
112
- - `actorType`
113
- - `reason`
114
- - `cutoff`
115
- - `previousUpdatedAt`
116
-
117
- ## Evidence To Return
113
+ ```ts
114
+ maybeAchieveCourseFromEmbeddedQuizSuccess({ userId, quizId, pageId, commit: false })
115
+ maybeAchieveCourseFromEmbeddedQuizSuccess({ userId, quizId, pageId, commit: true })
116
+ ```
118
117
 
119
- For every feedback operation, report:
118
+ Only write after the dry-run proves eligibility.
120
119
 
121
- - feedback id,
122
- - instance name/id,
123
- - user email,
124
- - old state,
125
- - new state,
126
- - admin log slug,
127
- - whether an email was sent.
120
+ ## Common Pitfalls
128
121
 
129
- For bulk operations, include counts by instance and a short sample of ids.
122
+ - Do not trust the automatic AI comment over Marina’s Slack reply.
123
+ - Do not import forwarded email as one ticket if it contains multiple asks.
124
+ - Do not close a feedback before prod deploy is live when the fix depends on deploy.
125
+ - Do not use inline body strings for real feedback reply emails.
126
+ - Do not say “fixed” until the prod row and customer-visible state are verified.