Skip to content

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

jc-academy-debug

Verified

JapaConnect Academy — Review & Debugging Skill

Conventions and gates: jc-academy-develop. Run in order.

0. API-Readiness First

Data not loading → verify the route exists before debugging frontend. Missing → ⚠️ MISSING BACKEND API ROUTES alert, pause.

1. SSR/CSR Boundary (Academy's #1 Bug — Critical)

  • ANY +page.server.ts fetching /api/v1/academy/progress/*, enrollment status, or completed lessons → Critical defect (progress leaks between users via cached SSR)
  • CSR progress fetch guarded by if (!data.session) return
  • SSR HTML contains no user-specific data (names, progress %, emails)
  • Course content (title, curriculum structure, lesson HTML) correctly SSR

2. TipTap Content

{@html} inside .prose · images via imgproxy URLs · syntax highlighting post-render ($effect + if (!browser) return + dynamic import) — never in SSR bundle.

3. Video Player

Init browser-guarded · destroyed on unmount · iframe embeds have title attribute + loading="lazy".

4. Mark Complete Races

marking guard prevents concurrent PATCH · completedIds is Set<number> with new Set() reassignment for reactivity · optimistic + rollback · next-lesson navigation only after successful PATCH.

5. Curriculum & Progress

<Accordion.Root type="multiple"> · locked lessons: lock icon, non-navigable, aria-disabled · active lesson highlighted · progressPercent = $derived(completedIds.size / totalLessons * 100) reactive to completion.

6. LayerChart

Apply jc-main-debug §4 (containers, colors, Date conversion, skeletons, tooltip import alias). Academy-specific: activity charts must not render before session-guarded data loads.

7. SEO

Course JSON-LD on overview, LearningResource on lessons · canonicals point to academy.japa.to.

8. Standard Checks

Apply jc-main-debug §§1–3, 5–7 (SSR/hydration, Runes, Bits UI, Tailwind, a11y).

9. Japa Academy Marketplace (ADR-063)

  • Wrong shell: Academy always renders the unified shell — there is no separate branded variant. If a custom domain should resolve to Academy, verify the academy.subdomain/academy.custom_domain system_settings and the edge proxy host routing.
  • Marketplace catalog shows unpublished courses: GET /academy/tracks must filter is_published_to_academy = true — if draft/unapproved courses appear, the backend filter is missing or the frontend is calling the wrong endpoint (/academy/tracks instead of /academy/tracks).
  • Creator application status stuck: academy_instructor_profiles.status not updating after admin approval — check the admin approval route and academy:notify_instructor_approved task wiring.
  • Price display wrong: price_kobo is in kobo (integer) — display as formatted currency. NULL price = "Free" or "Pro" (check user's Pro status). Don't show raw kobo value.
  • Instructor dashboard data leak: payout/revenue data must be CSR (session-guarded) — if it appears in SSR HTML, that's a critical SSR/CSR boundary violation (same class as §1).
  • Pro dual-access not reflected: Pro subscriber sees a price instead of "Included with Pro" — check Pro status check before rendering price.
  • Course reviews missing: reviews should use the polymorphic reviews table (entity_type = 'academy_track') — if a separate review system was built, that's a defect (ADR-063 §2: reuse, no course_reviews table).

Output Protocol

  1. Root cause · 2. Broken code · 3. Fixed code · 4. Secondary findings

App Shell & LayerChart (ADR-060 / ADR-059)

  • Academy uses the unified shell (ADR-058) adapted per ADR-060: collapsible left nav (learning-oriented, state via ui.nav_collapsed server-side — not localStorage), center, right sidebar (continue/streak/up-next). Flag surfaces built as a top-nav or standalone layout.
  • Lesson player is Academy's reading exception: collapsed nav + CurriculumRail (borderless, part of the content — not a second nav) + lesson-meta panel. Flag two-sidebar-looking rails.
  • TrackCard is one variant-driven card — flag per-level/type card forks.
  • Charts: pinned layerchart@2.0.1, colors via CSS vars, fixed height, Gate-verified data, per-chart skeleton — flag unpinned/@next or hardcoded chart colors.
  • Enforce the SSR/CSR boundary: user progress/enrollment must be CSR, never in +page.server.ts. V2 academy app: No new pages in v2. Japa Academy (ADR-063) is already implemented. The academy app may receive minor amendments if Japa Academy course visibility is affected by v2 persona authorship or the AI Content Studio publishing courses. Per ADR-060, v2 community features (§§79–89), functional tools (§§90–101), and mentorship (§102) are not part of the academy platform — they live in the Main app (community) and Tools app (functional tools). However, academy content may be cross-referenced from these features (e.g. a functional tool may link to a relevant academy track). Total platform route count is now ~819 (~475 v1 + ~344 v2); 18 Golden Rules (R18: always use bun).

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: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
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