Skip to content

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

jc-docs-debug

Unverified

JapaConnect Docs — Review & Debugging Skill

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

0. API-Readiness First

Data not loading → verify route before debugging (⚠️ alert if missing, pause). Sidebar empty? Check /api/v1/docs/sections responds — do NOT hardcode a fallback tree.

1. Observer/Listener Leaks (Docs' #1 Bug)

  • IntersectionObserver in $effect MUST return () => observer.disconnect() — accumulation breaks anchor highlighting and leaks memory
  • Cmd+K window.addEventListener('keydown', ...) MUST return removeEventListener cleanup — stacked listeners open multiple dialogs
  • Any ResizeObserver/setInterval similarly cleaned up

2. Cmd+K Search

<Combobox.Input> auto-focused on dialog open · first focusable inside <Dialog.Content> · Escape closes without Combobox conflict · debounce cleanup (return () => clearTimeout(id)) · results from /docs/search not local filtering.

3. Code Blocks

Highlighting in $effect + browser guard + dynamic import (not in SSR bundle) · re-runs on route change (new page content) · copy reads textContent not innerHTML · "Copied!" tooltip resets after ~2s.

4. Sidebar

From /api/v1/docs/sections (Rule 16) · active page tracks $page.url.pathname · mobile drawer is <Dialog.Root> with focus trap, focus returns to hamburger on close · nav data cached (no re-fetch per internal navigation).

5. Responsive Collapse

Three→one column at breakpoints · right panel hidden ≤ tablet · no horizontal overflow at any width.

6. {@html} Safety

Only for backend TipTap-rendered docs content — flag any other instance.

7. Standard Checks

Apply jc-main-debug §§1–3, 5–7 (SSR/hydration, Runes, Bits UI, Tailwind, SEO, a11y). LayerChart checks (jc-main-debug §4) if usage-stat charts present.

8. Japa Academy & Geo API Docs (ADR-063/064)

  • Missing API reference pages: if the new v1.11.0 routes (/geo/me, /academy/*, /universities, /admin/universities, /me/payouts) don't have API reference pages, that's a docs gap — flag it
  • ?geo= param not documented: feed/search/trending routes should document the ?geo= default behavior (ContentCountry when absent, ?geo=all for global)
  • price_kobo unit confusion: if docs show price_kobo without specifying it's an integer in kobo (not naira), flag it
  • is_published_to_academy vs is_published: if docs conflate these two flags, flag it — they're distinct (marketplace visibility vs platform publish)

Output Protocol

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

App Shell & Docs Drift (ADR-060)

  • Docs uses the unified shell (ADR-058) adapted per ADR-060: the left nav IS the audience-gated doc nav tree (from GET /api/v1/docs/nav), collapsible (ui.nav_collapsed server-side, not localStorage); the right sidebar IS the in-page TOC + "was this helpful?" — flag social-widget sidebars or a hardcoded nav tree.
  • API reference adds a right code-sample pane; the API Playground is the full-width tool exception — flag a playground crammed into the three-column shell.
  • Audience gating is server-side only (403 → /docs/access-denied) — flag any client-side permission hiding.
  • ⌘K search + TOC observers must clean up in $effect return.
  • Any usage-stat charts use pinned layerchart@2.0.1, CSS-var colors, fixed height. V2 docs app: No new pages in v2. Docs app requires stable API surface (OpenAPI spec from §47). The japaconnect_core Flutter package will use the same OpenAPI spec — ensure spec remains current when v2 backend phases land. JEOS v1.22.0–v1.23.1 updates (§§79–102, ADRs 087–110):
  • OpenAPI spec must cover the new ~344 v2 routes (§§60–102) — the spec from §47 must be extended to include all v2 community feature routes (§§79–89, §98), functional tool routes (§§90–97, §§99–101), and mentorship routes (§102). Total platform route count is now ~819 (~475 v1 + ~344 v2).
  • New ADRs 087–110 need documentation pages — each ADR should have a docs page in the architecture/ADRs section. Key ADRs: ADR-088 (universal AI content generation), ADR-042 (feature-flag 404 not 403), ADR-110 (mentorship matching).
  • New sections §§79–102 need API reference documentation — 24 new sections covering 11 v2 community features, 12 V2 functional tools, and mentorship matching. Each section's endpoints need three-column API-docs variant pages with method badges and Request/Response/Example tabs.
  • Geo-aware tool pattern needs a docs page — .jeos/skills/geo-aware-tool-pattern.md describes the destination-country-as-primary-axis pattern. This needs a public docs page explaining the ?dest= filter, destination_country_id schema field, destination selector UX, and feature-flag 404 behavior.
  • ADR-088 AI content generation columns need documentation: ai_generated, ai_model, hitl_reviewed_by, ai_generated_at, is_japabot_indexed — document these as standard columns on all v2 tool content tables, with HITL review mandatory before publish.
  • 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: 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