servicenow-atlas: Skill for Claude Code

When to use

• Adding a new dependency — always ask "can I do this with numpy/pyarrow?"
• Choosing a data structure for the chunks table
• Writing startup/import-heavy code
• Adding CPU-bound parallel work
• Any change to atlas/ source files

Principles

1. Zero new deps. Every library adds import time, CVE surface, and lockfile bloat. Prefer numpy + pyarrow (already installed) over anything new. Pandas is explicitly banned — see patterns below.

2. Optimize startup, not just hot path. A ~300 ms pandas import on every atlas-* command hurts more than a 10 ms saving in a rarely-hit code path.

3. DataFrame abstractions are overhead. The chunks table is read-only, loaded once, and accessed by column. Store columns as numpy arrays for masks and list[str] for string data. Index by position, not by label.

4. C-level string ops when possible. Use pyarrow.compute (match_substring) instead of Python loops over 250k strings. Use pc.match_substring(arrow_array, token) — it's the same speed as pandas str.contains.

5. Process-level parallelism for CPU-bound ONNX. ONNX session.run is CPU-bound. Use concurrent.futures.ProcessPoolExecutor with min(os.cpu_count(), 4) workers, each loading its own ONNX session. Only for onnx-cpu backend — MLX and CUDA are sequential.

6. Lazy init for argparse and other I/O. Never call parse_args() or read_parquet() at module level. Use the _get_args() / _bundle_cache double-checked locking pattern from rag_server.py.

7. Pre-compute at build time. Norms, manifest SHAs, anything that can be computed once and stored. Query time should be as close to a single matrix multiply as possible.

8. Single matrix multiply for cosine similarity. 250k × 768 dims: (embeddings @ query).flatten() / norms. No FAISS, no Qdrant, no vector database. Numpy is sufficient and has zero infrastructure.

9. Don't rebuild what's already built. The bundle is the slowest thing we produce (~15 min MLX, hours on CPU). Default to publishing the existing ./data/rag-bundle. Only rebuild when the docs source has changed. This is encoded in scripts/publish-bundle.sh.