Skip to content

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

jc-docs-audit

Verified

JapaConnect Docs — Audit Skill

Work file-by-file. Conventions: jc-docs-develop.

A. Memory Leak Audit — Critical (Run First)

SubscriptionRequired cleanup
IntersectionObserver$effect returns disconnect()
window keydown (Cmd+K)$effect returns removeEventListener
setTimeout debounce$effect returns clearTimeout
setInterval / ResizeObservercleared/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 to ContentCountry, explicit ?geo=all for global)
  • price_kobo documented as integer (kobo), is_published_to_academy documented as distinct from is_published
  • University spaces (Section 39) university_fields custom 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_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) — 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.md needs a public docs page explaining the ?dest= filter, destination_country_id schema 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)

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.

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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall