jedafe/japa / .claude/skills/jc-admin-debug
jc-admin-debug
UnverifiedUse when reviewing or debugging JapaConnect Admin Panel code (apps/admin, SPA). Diagnoses DataTable spec violations, RBAC gaps, SPA auth issues, LayerChart problems, and Svelte 5/Bits UI errors.
JapaConnect Admin Panel — Review & Debugging Skill
Conventions and gates: jc-admin-develop. Run checks in order.
0. Gates First
- Data not loading? Verify the route exists before debugging frontend. Missing → ⚠️ MISSING BACKEND API ROUTES alert, pause.
- Entity page missing an action (edit, delete, unban)? Check if the backend route exists. Missing → ⛔ MISSING RBAC CRUD ENDPOINTS alert, pause. A frontend "fix" that hides the action is NOT acceptable — super-admin CRUD is non-negotiable.
1. DataTable Spec Violations
Check the page against the mandatory spec — flag every miss:
- Sortable columns (URL-param driven, survives navigation)
- Search input wired to
?q=, debounced - Filter panel wired to
?filter= - Pagination with page-size selector from API
meta - Action column with View + Edit + Delete on every row
- State actions (Suspend/Unsuspend, Ban/Unban, Approve/Reject) present AND conditional on current state — a banned user's row must show Unban, not Ban
- Bulk checkboxes + select-all + contextual bulk bar
- Create button (top) on non-readonly entities
- Readonly entities still have Delete/Remove/Clear in the action column
- Bulk selection reset on page change · destructive actions behind
<Dialog.Root>confirmation (neverwindow.confirm) · View opens a modal, never navigates
2. SPA Auth
Root layout ssr=false/prerender=false · auth guard $effect + goto('/login') on every protected route · no +page.server.ts files · goto() not window.location.href · 403 → permission error UI, not blank screen.
3. Data Fetching
$effect (not onMount) so param changes re-fetch · reactive params inside effect scope · try/catch + error state + finally { loading = false } · $derived for computed counts.
4. LayerChart
Fixed-height container present · colors var(--color-*) only (test dark mode) · API date strings → Date objects · data from /api/v1/admin/analytics/* not hardcoded · skeleton per chart · LayerChart Tooltip vs Bits UI Tooltip import collision — alias one (import { Tooltip as ChartTooltip } from 'layerchart').
5. RBAC UI
Permission-node checks (session.permissions.includes(...)) not role-string checks · destructive controls hidden/disabled without permission · state-action buttons permission-gated individually (ban ≠ suspend permission). Japa Academy: academy.instructor.approve ≠ university.instructor.suspend ≠ academy.course.approve ≠ academy.payout.process — each is a separate node, gate each action individually.
6. Bits UI / Svelte 5
Apply the full violation tables from jc-main-debug sections 2–3.
6b. Japa Academy Admin (ADR-063 + Section 39)
- Instructor approval missing both directions: approve without reject (or vice versa) — Gate 2 requires BOTH directions of every state transition. A pending instructor must have Approve AND Reject; an approved instructor must have Suspend AND Unsuspend.
- Payout method exposed:
academy_instructor_profiles.payout_method(jsonb) shown raw in the admin UI — Critical security finding. Must be masked. - University course approval one-directional: only Approve without Reject — both required. Approve sets
is_published_to_academy = true; Reject keeps it false. - Payout state machine broken:
academy_instructor_payoutsstatus must go pending→processing→paid or →failed. A jump from pending to paid (skipping processing) or from paid back to pending is a defect. - University logo not uploading: logo upload must go through Section 34 media (SeaweedFS + imgproxy) — if it's stored as a raw URL string, that's a defect.
7. Accessibility
<th scope="col"> + aria-sort on sortable headers · bulk buttons disabled (not hidden) when nothing selected · focus returns to trigger on dialog close · aria-live="polite" on table container during load.
8. V2 (JEOS v1.23.1) Debug Patterns
Debug patterns for §§79–102 admin surfaces (Phases 24–27). ~819 routes total (~475 v1 + ~344 v2), 297 RBAC nodes, 18 Golden Rules.
- Missing ADR-088 columns on admin content tables: An admin content table for §§79–101 (stories, wiki revisions, scam alerts, digests, AMAs, services, arrival checklists, housing guides, attestations, tax guides) is missing one or more of
ai_generated,ai_model,hitl_reviewed_by,ai_generated_at. Symptom: admin form has no HITL review step, or AI-generated content can be published without review. Fix: add the missing columns via migration, update the admin form to requirehitl_reviewed_bybefore publish. - HITL review gate bypassed: Content with
ai_generated = trueis in published/active state buthitl_reviewed_byis NULL. Symptom: AI-generated story/wiki revision/digest visible to users without human review. Root cause: the publish/approve endpoint doesn't checkhitl_reviewed_bywhenai_generated = true. Fix: enforce server-side check — reject publish ifai_generated = true AND hitl_reviewed_by IS NULL. - Geo-aware filter missing (?dest= not implemented): A §§90–97 or §§99–101 tool admin list endpoint doesn't accept
?dest=parameter, or the DataTable filter panel lacks a destination country dropdown. Symptom: admin can't filter tool content by destination country, or nationality is hardcoded in the query. Fix: add?dest=filter param to the endpoint, add destination dropdown to the filter panel, remove any hardcoded nationality from queries. - Feature-flag returning 403 instead of 404: A disabled v2 feature endpoint returns HTTP 403 (Forbidden) instead of HTTP 404 (Not Found) per ADR-042. Symptom: admin UI shows a permission error instead of "feature disabled" for a v2 feature that hasn't been enabled yet. Fix: update the feature-flag middleware to return 404 when a feature is disabled (not 403). The admin frontend should handle 404 as "feature not available" rather than "permission denied."
- Admin list using infinite scroll instead of pagination: A v2 admin list page uses infinite scroll or "load more" instead of the standard DataTable pagination with page-size selector. Symptom: no page-size selector (25/50/100), no pagination navigation, URL params don't include
?page=&limit=. Fix: replace infinite scroll with standard DataTable pagination, ensure the API endpoint returnsmetawith total count + page info. - Mentorship active_mentee_count computed at query time (trigger missing): The mentor list endpoint computes
active_mentee_countvia aCOUNT(*)subquery or join instead of reading the maintained column. Symptom: mentor list is slow, oractive_mentee_countis inconsistent with actual mentee connections. Root cause:trg_mentee_countPostgreSQL trigger is missing or disabled. Fix: create/enable the trigger that maintainsactive_mentee_counton INSERT/UPDATE/DELETE of mentee connections, remove the query-time computation from the endpoint.
Output Protocol
- Root cause (one sentence) · 2. Broken code · 3. Fixed code · 4. Secondary findings
V2 admin phases (20–27): Persona Management + Content Studio (Phase 20) → Newsletter + Jobs (Phase 21) → Gamification/Analytics/Commerce (Phase 22) → QA (Phase 23) → Community Features Admin (Phase 24) → Tools Admin + HITL Queues (Phase 25) → QA Update (Phase 26) → Mentorship Admin (Phase 27). See
ROADMAP-ADMIN.mdfor task breakdown.
New admin surfaces in v2: AI Persona management (/admin/personas), Content Studio (/admin/studio), Participation queue (tab in moderation queue), RAG index status widget, Remittance provider management, Newsletter composer, Gamification badge/challenge CRUD, Advanced analytics dashboard.
V2 community features admin (Phase 24, §§79–89, §98): Story verification (§79), wiki revision approval (§80), scam alert moderation (§81), planning group management (§82), visa timeline admin (§83), digest generation/publish (§84), mutual aid moderation (§85), calendar review (§86), japa stage profiles (§87), AMA moderation (§88), achievement management (§89), service directory verification/claim review (§98). All admin-managed content tables must carry ADR-088 AI generation columns (ai_generated, ai_model, hitl_reviewed_by, ai_generated_at) with mandatory HITL review before publish. Admin list endpoints must filter + sort + paginate (no infinite scroll).
V2 functional tools admin (Phase 25, §§90–97, §§99–101): Visa route management (§90), embassy polling configuration (§91), arrival checklist approval (§92), processing time tracker (§93), credential checker management (§94), CV formatter standards (§95), housing guide management (§96), attestation approval (§97), language test requirements (§99), tax guide/treaty management (§100), community locator review (§101). All tools follow the geo-aware tool pattern — destination country is the primary data axis, no hardcoded nationality, ?dest= filter on list endpoints.
V2 mentorship admin (Phase 27, §102, ADR-110): Mentorship connection management, mentor profile review. Verify active_mentee_count is maintained by PostgreSQL trigger (trg_mentee_count), not computed at query time. Match scoring is 60% keyword overlap + 40% pgvector cosine similarity.
V2 Feature Areas (Implement Only After Corresponding Backend Phase Is Complete)
| Feature | Backend phase | Key sections | Gates |
|---|---|---|---|
| JapaBot (RAG-grounded) | Phase 41 | §69 | /ai/chat amended |
| AI Content Studio (admin) | Phase 42 | §75 | studio.* RBAC |
| Participation queue (admin) | Phase 42 | §76 | participation.review RBAC |
| Visa Checklist | Phase 43 | §70 | checklist.use RBAC |
| Readiness Assessment | Phase 43 | §71 | assessment.take RBAC |
| Cost of Living Calculator | Phase 43 | §72 | col_calculator.use RBAC |
| Scholarship Finder | Phase 43 | §73 | scholarship.browse RBAC |
| Remittance Rate Tracker | Phase 44 | §74 | remittance.view RBAC |
| Referral system | Phase 45 | §60 | referral.use RBAC |
| Self-serve ads | Phase 45 | §61 | ads.self_serve.create RBAC |
| Newsletter | Phase 45 | §62 | newsletter.subscribe RBAC |
| Jobs board | Phase 45 | §63 | jobs.browse RBAC |
| Gamification | Phase 45 | §64 | gamification.view RBAC |
| Content import | Phase 46 | §65 | import.use RBAC |
| Advanced analytics | Phase 46 | §66 | analytics.advanced RBAC |
| Travel search | Phase 46 | §67 | travel.search RBAC |
API-Readiness Gate applies to all v2 features. Verify against api-routes-catalog.md — all v2 routes are marked as "V2 planned" in the catalog. Once the corresponding backend phase lands, the planned routes become available.
Removed surface: apps/tools was consolidated into apps/main (/tools/{tool}) — ADR-086 superseded. tools.japa.to and per-tool subdomains 301 to japa.to/tools/{tool}; the jc-tools-* skills were deleted.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |