Skip to content

jedafe/japa / .claude/skills/jc-admin-debug

jc-admin-debug

Unverified

Use 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 (never window.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_payouts status 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 require hitl_reviewed_by before publish.
  • HITL review gate bypassed: Content with ai_generated = true is in published/active state but hitl_reviewed_by is NULL. Symptom: AI-generated story/wiki revision/digest visible to users without human review. Root cause: the publish/approve endpoint doesn't check hitl_reviewed_by when ai_generated = true. Fix: enforce server-side check — reject publish if ai_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 returns meta with total count + page info.
  • Mentorship active_mentee_count computed at query time (trigger missing): The mentor list endpoint computes active_mentee_count via a COUNT(*) subquery or join instead of reading the maintained column. Symptom: mentor list is slow, or active_mentee_count is inconsistent with actual mentee connections. Root cause: trg_mentee_count PostgreSQL trigger is missing or disabled. Fix: create/enable the trigger that maintains active_mentee_count on INSERT/UPDATE/DELETE of mentee connections, remove the query-time computation from the endpoint.

Output Protocol

  1. 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.md for 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)

FeatureBackend phaseKey sectionsGates
JapaBot (RAG-grounded)Phase 41§69/ai/chat amended
AI Content Studio (admin)Phase 42§75studio.* RBAC
Participation queue (admin)Phase 42§76participation.review RBAC
Visa ChecklistPhase 43§70checklist.use RBAC
Readiness AssessmentPhase 43§71assessment.take RBAC
Cost of Living CalculatorPhase 43§72col_calculator.use RBAC
Scholarship FinderPhase 43§73scholarship.browse RBAC
Remittance Rate TrackerPhase 44§74remittance.view RBAC
Referral systemPhase 45§60referral.use RBAC
Self-serve adsPhase 45§61ads.self_serve.create RBAC
NewsletterPhase 45§62newsletter.subscribe RBAC
Jobs boardPhase 45§63jobs.browse RBAC
GamificationPhase 45§64gamification.view RBAC
Content importPhase 46§65import.use RBAC
Advanced analyticsPhase 46§66analytics.advanced RBAC
Travel searchPhase 46§67travel.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.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall