jedafe/japa / .claude/skills/japa-docs-author
japa-docs-author
VerifiedJapaConnect Docs Author — Repo docs/ Writer
Writes engineering documentation into the repo docs/ directory. Ground truth is .jeos/ (the spec) verified against shipped code — never write from memory. JapaConnect has ~158 tables, ~819 routes, 118 section files; your training data does not contain them. The files do.
⛔ LOAD-ORDER GATE
Before writing a single line of a doc:
.jeos/JEOS.md— the master index. Find which sections/conventions/ADRs own the thing you're documenting..jeos/.ai/*.yaml— orientation layer:project.yaml,architecture.yaml,stack.yaml,domains.yaml,glossary.yaml,conventions.yaml. These are the machine-readable "how the site is built" summary..jeos/.ai/context/implementation-phase.md— current project STATE (what version, what shipped). Transient — never cite it as spec.- The specific
.jeos/sections/NN-*.mdfiles for the feature — the HOW. - Relevant
.jeos/conventions/*.md—api-routes-catalog.md,system-settings-catalog.md,valkey-keys-catalog.md,permission-key-naming.md,asynq-tasks.mdfor any route/key/task/setting you name. - Verify against code — spec can drift from shipped code (JEOS.md says so itself). Spot-check: does the route exist in
internal/server? Does the table exist inmigrations/? Does the permission node exist in seed data? If spec and code disagree, document the code and flag the drift explicitly in the doc ("JEOS §NN says X; shipped code does Y — drift flagged").
Writing docs from memory or from the spec alone, unverified, is a violation — same spirit as Rule 1/Rule 16.
Where docs go
| Content | Location | Naming |
|---|---|---|
| Foundational principles, constitution, architecture philosophy | docs/00-foundation/ | UPPER_SNAKE.md |
| Feature/design docs, guides, audits | docs/ root or a topic dir | kebab-case.md |
| Implementation plans | docs/superpowers/plans/ | YYYY-MM-DD-<slug>.md |
| Feature specs/design docs | docs/superpowers/specs/ | YYYY-MM-DD-<slug>-design.md |
Match the existing neighbors' structure. docs/superpowers/ files are date-prefixed — always use today's date.
Doc conventions
- Cite sources. Reference the owning spec in-line:
Ref: .jeos/sections/44-documentation-system.md,ADR-069,migrations/000735_baseline_schema.up.sql. A doc a reviewer can't trace back to a spec/code is a guess. - Real names only. Route paths must match
conventions/api-routes-catalog.md(or actual handler registrations). Table/column names must matchmigrations/. Valkey keys must matchvalkey-keys-catalog.md(jc:prefix). Asynq task names must matchsections/11-job-queue-asynq.md. Permission nodes must matchsections/03-rbac.md/ seed data. - Current truth markers. Note the JEOS version (
JEOS.mdheader) and date at the top of substantial docs; mark anything version-gated (v1 vs v2, roadmap status). - Rule 17 — no AI attribution. Never state or imply AI authorship anywhere in the doc.
- Rule 18 — bun for any JS/TS tooling commands you document (
bun,bunx,bun run— never npm/npx/pnpm/yarn). - Honest status. If a feature is spec-complete but unshipped, say so. Never document aspirational behavior as live behavior.
Structure for feature docs
- What it is (one paragraph — user-facing purpose)
- Where it lives (surfaces, routes,
internal/package, key tables) - How it works (data flow; the JEOS reference trail)
- API surface (routes table — verified against catalog/code)
- Configuration (feature flags via
features.Registry→ Control → Extensions;system_settingskeys; env vars) - Permissions (RBAC nodes that gate it)
- Background work (Asynq tasks, Valkey keys)
- Known limits / drift notes / open questions
What NOT to do
- Do NOT document a route, table, setting key, Valkey key, or task name you haven't verified exists in the catalog or the code.
- Do NOT copy spec prose wholesale — a doc explains the shipped system; the spec already exists in
.jeos. - Do NOT put public/user-facing guides here — user docs live in the docs system (
apps/docs+docs.*agent tools), not the repo. - Do NOT create README/index churn — add files where the existing tree puts them; update
docs/README.mdonly if it indexes siblings. - Do NOT leave
// QUESTION:-style gaps silently — if a spec is ambiguous, document what's verifiable and flag the gap.
Deliverables
- The doc file(s) in the correct location per the table above.
- Every factual claim traceable to a
.jeosfile or shipped code (Ref comments/links). - Drift flags where spec ≠ code, stated plainly in the doc.
- No AI attribution, bun-only tooling commands, catalog-exact identifiers.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |