sjarmak

Index of this project's coding-practice rules — architecture, coding style, testing, security, git workflow, task management, context layering, anti-slop, performance, and language-specific rules. The thin always-on essentials live in .claude/rules/common/house-rules.md; the full per-topic detail ships under .claude/rules/reference/ and .claude/rules/<lang>/ and is read on demand. Invoke this skill when you need the project's standards for a task, then open the specific rule file it points to.

Thin methodology for end-to-end tests of critical user journeys — define journeys by risk, use semantic locators and condition-based waits, quarantine flaky tests with a tracked reason, and capture artifacts on failure. Use when adding or stabilizing E2E coverage; the e2e-runner agent applies it in depth.

Design rigorous evaluations and benchmarks for AI agents, developer tools, retrieval systems, and repository-scale automation. Covers task selection, contamination control, metric choice tied to engineering decisions, and statistical validity. Use when asked to design an eval/benchmark, critique an existing benchmark, choose metrics for an agent or RAG system, or decide whether a measured improvement is real. NOT for running an existing performance-benchmark suite or a per-feature acceptance checklist, or one-off model spot-checks.

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree one at a time. Use for ambiguous or complex collaborative specs before any code is written.

Decision framework for choosing between regex and LLM when parsing structured text — start with regex, add LLM only for low-confidence edge cases. Use when parsing quizzes, forms, invoices, or documents with repeating structure and cost matters.

Review a repository for long-term architectural leverage rather than code quality — system structure, module boundaries, dependency graph, coupling, and drift. Produces a ranked set of highest-ROI improvements with evidence, effort, and risk. Use when asked to review the architecture, assess a codebase's structure/design, find where complexity is concentrated, or decide what to refactor next. NOT for style, naming, formatting, or line-level bugs (use a code-review skill for those).

Analyze a software system, AI pipeline, or research direction by surfacing its underlying structure — invariants, hidden abstractions, weak assumptions, and the single highest-leverage direction — rather than optimizing local implementations. Use when asked to step back and think about a system's design at a conceptual level, find leverage points, evaluate a research direction for compounding impact, or decide where to invest for the long term. NOT for reviewing a specific repo's architecture (use repo-architecture-review) or local code cleanup.

Structured brainstorming with research-driven exclusion zones and shape-uniqueness enforcement. Forces divergent thinking through volume and a hard constraint: no idea may take the same shape as any prior art or any earlier idea. Use when exploring solutions to a problem, designing features, or when the obvious approach might not be the best one.

Build, test, and CI runbook for SciX Experiments: recreate the venv and the optional-extras matrix (dev/qdrant/graph/mcp/embed/ner_pass/viz/...), run make check vs make check-ci, understand the "not integration and not network" marker filter, the optional-dependency collection guards in tests/conftest.py, the ci/scix_test_schema.sql snapshot the CI Postgres loads, the MCP contract-drift test, and the pinned black/ruff formatters. Load when setting up a fresh checkout, when CI is red and local is green (or vice versa), when tests skip silently or whole test modules vanish, when pre-commit or fmt-check fails, or when test_mcp_contract_conformance fails. NOT for prod-DSN/write-test safety semantics — use scix-db-safety-and-telemetry. NOT for changing the MCP tool surface itself — use scix-mcp-tool-surface. NOT for running heavy jobs on this host — use scix-memory-and-batch-discipline. NOT for what the project is — use scix-orientation.

How change is gated in SciX: which changes require an ADR (retrieval/vector/storage/dimensionality/quantization axes), the 15-tool MCP cap and contract regeneration, migration discipline (append-only, no auto-runner, the hand-applied 069-072 gap), which changes HALT at branch-ready for sign-off, where project truth lives (beads/ADRs, not git history), and what is intentionally retired vs parked. Also documents the Gas City bead/dispatch machinery (internal-orchestration). Load BEFORE proposing or landing any change to retrieval, vectors, storage, the tool surface, the schema, or prod data, or before re-landing anything from an old branch. NOT for how the retrieval stack works (scix-retrieval-architecture), DSN/prod-DB guards (scix-db-safety-and-telemetry), running heavy jobs safely (scix-memory-and-batch-discipline), or tool-surface internals (scix-mcp-tool-surface).

The SciX citation-graph layer: graph_metrics.py (PageRank/HITS/Leiden), the paper_metrics and communities tables, the (signal, resolution, community_id) model, the 299M-row citation_edges table, and the MCP citation/provenance tools (citation_traverse, forward_citations incl. the find_replications/cited_by_intent aliases, claim_blame, graph_context) with citation-intent classification. Load when computing or debugging PageRank, HITS, Leiden communities, community labels, citation traversal, claim provenance, replication finding, or citation intent. NOT for the RRF search stack (use scix-retrieval-architecture), NOT for the Qdrant dense lane or embeddings ingest (use scix-vector-serving-qdrant / scix-embedding-pipeline), NOT for MCP tool-cap/contract mechanics (use scix-mcp-tool-surface), NOT for the entity graph (use scix-entity-ner-system), NOT for query-side agent usage of the tools (use the existing scix-mcp skill).

Production-database protection and query_log telemetry for SciX. Load this BEFORE any command that opens a PostgreSQL connection in this repo: running pytest, setting SCIX_DSN / SCIX_TEST_DSN, calling is_production_dsn, passing --allow-prod to a script, wiping/seeding test tables, or analysing the query_log table (success/error_msg semantics, failure rates, guard-block counts). Triggers: "which database am I pointed at", "tests all passed but wrote nothing", "SCIX_TEST_DSN", "--allow-prod refused", "query_log says success", "failure rate by tool". NOT for memory/cgroup sizing or the scix-batch wrapper itself — use scix-memory-and-batch-discipline. NOT for schema-migration or index-build discipline — use scix-index-and-storage-discipline. NOT for what gets ADR-gated — use scix-change-control.

The INDUS paper-embedding ingest path: src/scix/embed.py, scripts/embed.py, daily_sync.sh Step 5, the paper_embeddings table and its PG-to-Qdrant outbox sync, and the s7cy live fire (paper_embeddings was DROP TABLEd out-of-process; committed HEAD embed code targets the dropped table; ~83K papers have no dense vector). Load when embedding new papers, debugging "relation paper_embeddings does not exist" / daily_sync aborts, backfilling the dense-vector gap, touching any embed/outbox/watermark code, or asking which embedding model/pooling/input format SciX uses. NOT for Qdrant collection config, serving reads, or payload indexes — use scix-vector-serving-qdrant. NOT for RRF fusion or lane weighting — use scix-retrieval-architecture. NOT for index DDL / disk reclamation — use scix-index-and-storage-discipline. NOT for DSN guards and prod-DB protection mechanics — use scix-db-safety-and-telemetry. NOT for scix-batch/OOM discipline details — use scix-memory-and-batch-discipline.

Maintainer guide to the SciX cross-discipline entity graph and NER system: the entities / document_entities schema (57.7M paper-entity links), the three extraction lanes (LLM batch extraction, lexical linking, the GLiNER dbl.3 zero-shot pass), the INDUS post-classifier, the per-bucket precision profile and lower-bound honesty discipline, the eq95 denylist, the JIT resolver lane (bulkhead / canary / stubs), and the ZFC rule (classify via the entity graph, never keyword heuristics). Load when working on src/scix/extract/, src/scix/jit/, entity_resolver, resolve_entities, document_entities, NER precision, GLiNER, ner_quality_profile, or the entity MCP tool's internals. NOT for using the MCP tools as a literature researcher — use scix-mcp. NOT for the MCP tool cap / contract regen — use scix-mcp-tool-surface. NOT for citation communities / PageRank — use scix-citation-graph. NOT for embedding ingest — use scix-embedding-pipeline.

How retrieval and extraction quality is measured and what counts as evidence in SciX: the gold sets (50q curated, 1200q recall gold, claim extraction, lexical stress), the fusion-calibration sweep and its honest verdict (dense_only < bm25_only), nDCG@10 / Recall@K / MRR, Wilson 95% CIs, the OAuth persona/UMBRELA judges, the claim_blame gold-set plan (bead 6ajy), and the reporting rules (read-only harness, lane provenance, per-bucket numbers, null results stated plainly). Load when running or interpreting an eval, adding a gold set, judging relevance, choosing an acceptance threshold, or writing up a result. NOT for RRF fusion internals (scix-retrieval-architecture), Qdrant mechanics (scix-vector-serving-qdrant), CI/pytest (scix-build-test-ci), whether a change needs an ADR (scix-change-control), or query_log telemetry (scix-db-safety-and-telemetry).

How index and storage changes are made safely in SciX. Load BEFORE building, rebuilding, dropping, or benchmarking any Postgres index (HNSW, GIN, DiskANN, expression indexes); before any halfvec/quantization change; before reclaiming disk (DROP INDEX vs DELETE vs DROP TABLE, VACUUM FULL, pg_repack); before placing new data on DS (local NVMe) vs NAS (/mnt, NFS); and when working the ADR-015/016 reclamation line or the dqfe quantization spike. Covers the four don't-trust-a-new-index rules (bead 12rp, the 56-hour DiskANN loss), the halfvec shadow-column cutover and its planner traps, the disk-at-99% crisis, and never-live-write-on-NAS. NOT for Qdrant serving (scix-vector-serving-qdrant), the embed pipeline (scix-embedding-pipeline), DSN guards (scix-db-safety-and-telemetry), or change approval (scix-change-control).

Decompose a PRD into parallel work units and build them with independent agents

Run /prd-build over multiple PRDs with full worktree lifecycle (create, dispatch, FF-merge, cleanup). Single-command dispatch from one session — sequential or parallel.

Evaluate an MCP tool's agentic usability via parallel test scenarios plus a meta-reflection pass, producing a scored improvement report

Cancel or pause a PRD build run

Resume a paused or interrupted PRD build run

Show PRD build orchestration status

Run diverge → converge → premortem pipeline to produce a risk-annotated PRD

"Structured brainstorming with research-driven exclusion zones and shape uniqueness enforcement. Forces divergent thinking through volume and a hard constraint: no idea can take the same shape as any prior art or any previous idea. Use when exploring solutions to a problem, designing features, or when the obvious approach might not be the best one."

Run the codeprobe calibration gate and emit a curator profile when the R11 validity thresholds are met. Compares two curators over a holdout and enforces minimum tasks, minimum repos, and Pearson correlation before accepting. Triggers on calibrate curator, calibration gate, validity gate, curator profile, r11 gate, pearson correlation. Use this when a new curator version needs to be qualified before it is used in mining or scoring pipelines.

Diagnose mined-task infrastructure for drift and offline readiness. Compares metadata.json capability snapshots to live capabilities and runs credential-TTL preflight for airgapped runs. Triggers on check infra, capability drift, preamble drift, offline preflight, credential ttl, airgapped run readiness. Use this before running mined tasks that were produced on a different machine or weeks ago.

Analyze eval results from codeprobe runs. Compares configurations statistically, ranks by score and cost-efficiency, and produces actionable recommendations in JSON or pretty text. Triggers on interpret results, analyze eval results, compare configurations, rank agents, score regression, plot regression. Use this when the agent needs to turn a `codeprobe run` output directory into structured analysis.

Mine eval tasks from a repository's history using the codeprobe CLI. Extracts real code-change tasks from merged PRs/MRs with ground truth, test scripts, and scoring rubrics. Triggers on mine tasks, extract tasks, propose tasks, benchmark my repo, eval my repo, discover tasks. Use this when the agent needs to produce a reusable task suite from a codebase.

Execute eval tasks against an AI coding agent using the codeprobe CLI. Spawns isolated per-task sessions, scores with automated tests, and emits NDJSON events plus a terminal envelope. Triggers on run eval, run tasks, benchmark agent, evaluate agent, score agent, compare agents. Use this when the agent needs to produce scored results on a mined or scaffolded task suite.

Answer insight-style questions about recent dev/AI/research news using the code-intel-digest local mirror (hourly-refreshed Postgres). Use when the user asks what's trending, wants a weekly roundup/podcast-script, asks how a topic is being discussed, or wants a ranked list of items to read. Requires the code-intel-copilot MCP server to be registered (`claude mcp add code-intel-copilot -- npx tsx /absolute/path/to/src/mcp/server.ts`).

Weekly share-ready digest from the code-intel-digest mirror, formatted for Stephanie to paste/forward to internal team Slack/email or use as sales enablement / competitive intel. Output is polished enough to ship with light editing. For personal catch-up, use orient-digest instead. Requires the code-intel-copilot MCP server.

Weekly personal orientation digest for Stephanie over the code-intel-digest mirror. Use when she wants to catch up on the last ~7 days of AI/dev/research news for herself (not to share). Signal-dense, terse, assumes Stephanie-level context. For share-ready output, use distill-digest instead. Requires the code-intel-copilot MCP server.

Generate a weekly podcast (script + rendered mp3) from the code-intel-digest mirror. Configurable length (default 30 min). Use when Stephanie says 'make me a podcast', 'generate this week's podcast', 'render the digest as audio', etc. Produces both the markdown script and the mp3 in out/. Requires the code-intel-copilot MCP server.

Creates or updates AGENTS.md with standard workflow sections including Design Principles, Bead Closure, Workflow, Landing the Plane, Issue Tracking, and Agent Best Practices.