jedafe/japa / .claude/skills/jc-docs-audit
jc-docs-audit
VerifiedJapaConnect Docs — Audit Skill
Work file-by-file. Conventions: jc-docs-develop.
A. Memory Leak Audit — Critical (Run First)
| Subscription | Required cleanup |
|---|---|
| IntersectionObserver | $effect returns disconnect() |
| window keydown (Cmd+K) | $effect returns removeEventListener |
| setTimeout debounce | $effect returns clearTimeout |
| setInterval / ResizeObserver | cleared/disconnected |
| Verify by navigating between 10 docs pages — single observer/listener set in DevTools. Any missing cleanup → Critical. |
B. API Consumption Verification
Every route confirmed against catalog/probe (⚠️ block if missing). Sidebar MUST come from /api/v1/docs/sections — hardcoded tree = Critical Rule 16 violation.
C. Search Modal
<Dialog.Root> + <Combobox.Root> composition · autofocus · 200ms debounce · grouped results · full keyboard path (Cmd+K → arrows → Enter → Escape).
D. Code Blocks
Language badge · copy button (textContent, tooltip confirmation, screen-reader announce) · post-render dynamic-import highlighting · dark-mode contrast of syntax colors.
E. On-This-Page
Live-DOM heading extraction · IntersectionObserver tracking · smooth anchor scroll · hidden on mobile · role="navigation" + aria-label.
F. Responsive Layout
Column collapse at breakpoints · <Dialog.Root> mobile drawer with focus trap · no horizontal overflow.
G. SEO & Structured Data
Per page: title, description, canonical → docs.japa.to, TechArticle JSON-LD · landing: WebSite + SearchAction JSON-LD · API reference: appropriate WebPage schema.
H. LayerChart (If Usage Stats Present)
Apply jc-main-audit §E.
I. Standard Compliance
Apply jc-main-audit §§B (Rule 16), D (Bits UI), B(runes), G (security/{@html}), H (a11y — plus code-region roles, copy-button labels, nav landmarks, external-link rel), I (i18n).
J. Japa Academy & Geo-Aware API Docs (ADR-063/064)
- API reference pages exist for the new v1.11.0 routes:
GET /geo/me,GET /geo/lookup,/academy/*,/me/instructor-profile,/me/payouts,/universities,/admin/universities— flag any missing ?geo=param behavior documented on feed/search/trending/discovery routes (defaults toContentCountry, explicit?geo=allfor global)price_kobodocumented as integer (kobo),is_published_to_academydocumented as distinct fromis_published- University spaces (Section 39)
university_fieldscustom field group documented - All new routes use the three-column API-docs variant with method badges and Request/Response/Example tabs
Report Format
Same structure as jc-main-audit with categories: Memory leaks · API routes/sidebar · Search modal · Code blocks · On-This-Page · Responsive · SEO · Bits UI · Svelte 5 · A11y · Japa Academy/Geo API docs (ADR-063/064).
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) — flag if the spec from §47 doesn't include 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 — flag any missing ADR docs pages. 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. Flag any missing API reference pages.
- Geo-aware tool pattern needs a docs page —
.jeos/skills/geo-aware-tool-pattern.mdneeds a public docs page explaining the?dest=filter,destination_country_idschema field, destination selector UX, and feature-flag 404 behavior. Flag if missing. - ADR-088 AI content generation columns need documentation:
ai_generated,ai_model,hitl_reviewed_by,ai_generated_at,is_japabot_indexed— flag if these standard columns are not documented for v2 tool content tables. - 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 |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |