jedafe/japa / .claude/skills/jc-docs-debug
jc-docs-debug
UnverifiedJapaConnect 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
$effectMUST 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/setIntervalsimilarly 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=allfor global)price_kobounit confusion: if docs showprice_kobowithout specifying it's an integer in kobo (not naira), flag itis_published_to_academyvsis_published: if docs conflate these two flags, flag it — they're distinct (marketplace visibility vs platform publish)
Output Protocol
- 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_collapsedserver-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
$effectreturn. - 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). Thejapaconnect_coreFlutter 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.mddescribes the destination-country-as-primary-axis pattern. This needs a public docs page explaining the?dest=filter,destination_country_idschema 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)
| 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 |