Research code skill

Research Code Skill

For developers (human readers): all documentation in this skill is written in English, which is the source of truth. The agent always loads the English originals.

A skill that acts as the coding-standard layer of a research lab's ML/DL project. Rather than reviewing code after the fact, it lives in the agent's context and constrains every code operation as it happens. Its essence is twofold:

1. Project architecture 鈥?keep the lab's fixed project structure intact. As the agent writes or edits code, the architecture is the stable base: do not break it, do not invent a new layout, keep it clear and consistent.
2. Code-level conventions 鈥?within that architecture, every symbol and call follows uniform rules: naming, formatting, import/call style, and how configs compose.

These two axes are enforced in both core scenarios (build from zero, tidy an existing repo). The agent consults this skill before writing or editing any project code, so the codebase stays coherent by construction.

It distills thirteen authoritative references into four fused usage clusters, plus a coordination layer, into one shared convention set. Each cluster is one coherent concern the agent reaches for 鈥?the sources inside it compound, they do not stack:

1. Project Scaffold & Python Grammar (references/scaffold_grammar.md) 鈥?fuses Lightning-Hydra-Template (structure, LHT-*), Hydra configs (HY-*), and Google Python Style (GP-*): the layout, the config system that fills it, and the grammar that writes the Python in it.
2. Model & Component Design (references/model_design.md) 鈥?fuses PyTorch Lightning Style (PL-*, the model/system contract), timm architecture style (RC-TIMM-*, named architectures + models/{layers,blocks,architectures}), and OpenMMLab Registry (RC-OPENMMLAB-*, @X.register_module() + build_from_cfg): how a well-shaped, pluggable model looks.
3. Experiment Reproducibility (references/experiment_repro.md) 鈥?fuses Hydra Config-First (RC-HYDRA-*), FAIR data (RC-DATA-*), SemVer+Git Flow (RC-VER-*), and Meta Research philosophy (RC-META-*): the config鈫抎ata鈫抍ode鈫抏xperiment chain that makes a run regenerable.
4. Engineering Process & Interface Discipline (references/engineering_process.md) 鈥?fuses Software Engineering at Google (RC-ENG-*, review/change-size/docs) and Scientific-Python idiom (RC-SP-*, fit/predict, installable package, CI): what "good code" means as an engineering artifact. It also owns the Research Code Comment Standard (references/code_comments.md, COMMENT-*): research comments record intent / math / design decision / experiment constraint, not a line-by-line narration.
5. references/coordination.md + references/rule_cards.md 鈥?map all sources into one rule-code registry (LHT-/HY-/PL-/GP-* plus RC-* Rule Cards) so every convention is single, non-duplicated, machine-checkable.

Role in the workflow

This skill is a core part of the project context, not an optional utility. Treat it as the project's written engineering charter:

• Architecture first: the established structure (configs/, src/data, src/models, src/utils, entrypoints, root files) is the invariant. Every code operation respects it; never bypass or dismantle it.
• On project init (Scenario A), scaffold the structure from templates/project_skeleton/.
• On every code change (add / edit / delete a file or symbol), first check the relevant reference for the convention that applies, then write to match it.
• When naming anything (module, class, function, variable, config key, config file), apply the naming rules from the applicable reference.
• When the user's request would break a convention, follow the convention and briefly note the deviation you applied (do not silently diverge, do not silently invent).

Two core scenarios

This skill is used in exactly two situations. Both share the same invariant: preserve the project's architecture 鈥?it is the stable base; code is added and changed within it, never by breaking or bypassing it. Within that architecture, all code obeys the code-level conventions (naming, format, calling). Identify which scenario applies and follow its mode.

Two axes of regulation

1. Architecture (project level) 鈥?fixed structure: configs/ grouped by concern, src/data 路 src/models 路 src/utils, entrypoints, root files. Keep it clear; do not dismantle or reinvent it.
2. Code level 鈥?naming, formatting, import/call style, and config composition, uniform across every file.

Scenario A 鈥?Build from zero (greenfield)

The target is empty or does not yet exist. Use this skill to construct the whole project so it conforms from the first commit:

• Start from templates/project_skeleton/ (scaffold mode) to lay down the fixed architecture: directory structure, root files, configs/, src/.
• Write every new file strictly within that architecture: right directory, right module shape, right config composition, right names.
• This mode is forward-only; there is no existing code to reconcile.

Scenario B 鈥?Tidy an existing repository

The target is an existing repo with code that may not follow the conventions. Use this skill to bring it into the same architecture without breaking it:

• First audit the current state against the rule-code registry (run scripts/audit_style.py, or reason from the references) to enumerate gaps.
• Then restructure and rewrite to fit the fixed architecture: relocate files into src/, configs/<group>/; convert hardcoded args into Hydra configs; split models from systems; rename symbols per GP-NAME/PL-*; add missing root files and tests/.
• Preserve behavior while changing shape; reorganize by moving/renaming, and never arbitrarily delete or rewrite existing code. If a piece of code has no matching target folder, leave it in the project root rather than removing it. Never replace the architecture with a different one.
• Report the concrete changes made (a short "Convention applied" note per group of changes), and re-run the conformance gate to confirm.

When to Use

Apply this skill whenever the agent works in the research project:

• Scenario A (build): scaffold and write a brand-new research project that follows the conventions from day one.
• Scenario B (tidy): reorganize, rename, and refactor an existing repo so its architecture, naming, and configs conform to the standard.
• Ongoing code ops within either scenario: create / read / update / delete a file or symbol, or choose a name 鈥?always per the conventions.

Do NOT use this skill for:

• Pure frontend / web-only projects without a Python/ML backend.
• Non-Python languages (C++, JS) unless only the Google naming/text rules apply.

Preconditions

Before applying a convention, verify:

1. A target path is provided (repo root, directory, or specific files).
2. The change concerns Python code or Hydra YAML configs in the project.
3. Read access is available; Write/Edit only when the operation requires it.
4. For script execution, a Python 3.8+ interpreter is available.

If no target is given, ask the user for the path before proceeding. Decide the scenario: if the target is empty or absent, use Scenario A (scaffold, Procedure Step 5); if it already contains code, use Scenario B (tidy, Procedure Step 5鈫?).

Procedure

Apply the conventions as you work. Each step maps to a reference source; load only the reference for the operation at hand.

Lazy reference loading: read only the one cluster file under references/ for the concern being acted on. Do NOT load all at once 鈥? the four files are fused, pick the one that owns the concern.

• SCAFFOLD & GRAMMAR 鈫?references/scaffold_grammar.md (layout LHT-*, config HY-*, Python GP-*)
• MODEL & COMPONENT 鈫?references/model_design.md (PL-*, RC-TIMM-*, RC-OPENMMLAB-*)
• EXPERIMENT REPRO 鈫?references/experiment_repro.md (RC-HYDRA-*, RC-DATA-*, RC-VER-*, RC-META-*)
• ENGINEERING PROCESS 鈫?references/engineering_process.md (RC-ENG-*, RC-SP-*, COMMENT-*)
• cross-cutting → references/coordination.md + references/rule_cards.md
• BEHAVIORAL DISCIPLINE → references/rule_cards.md (RC-KARPATHY-*)

Always-on behavioral discipline (Karpathy -- applies to EVERY code action)

These four principles are summarized here so they stay in context for every edit; the full RC-KARPATHY-* cards live in references/rule_cards.md.

• Think Before Coding: state assumptions; if ambiguous, surface interpretations and ask instead of silently guessing. Stop and name confusion.
• Simplicity First: minimum code that solves the problem; no speculative features, abstractions, or error handling beyond the request.
• Surgical Changes: touch only what the request requires; match existing style; clean up only the orphans your change created.
• Goal-Driven Execution: turn imperative asks into verifiable goals (e.g. "write a test that reproduces the bug, then make it pass") and loop until the success criterion holds.

Caveat: bias toward caution over speed -- trivial one-liners (typo fixes) need not invoke full rigor.

Step 1 鈥?Project structure & Python grammar (Cluster 1)

Load references/scaffold_grammar.md (fuses Lightning-Hydra-Template layout, Hydra config system, and Google Python grammar), then place code per the layout:

• configs/ holds Hydra YAML configs grouped by concern (data/, model/, trainer/, callbacks/, logger/, experiment/, ...).
• src/ holds source split by role: src/data/, src/models/, src/utils/, with entrypoints src/train.py, src/eval.py.
• tests/ holds generic smoke tests; data/, logs/, notebooks/ are separated.
• Root files: .pre-commit-config.yaml, pyproject.toml (or setup.py), requirements.txt, .gitignore, .env.example, .project-root. When creating a file, put it under the matching directory (codes LHT-01..07).

Step 2 鈥?Config conventions (Hydra)

Load references/scaffold_grammar.md (CONFIG section), then write configs that:

• Use @hydra.main(version_base=..., config_path=..., config_name=...) at entrypoints, with rootutils.setup_root for location independence.
• Compose by group, override via CLI and @ defaults lists.
• Express each object as a _target_ plus primitive params.
• Resolve all paths via configs/paths/default.yaml (no hardcoded paths).
• Version-control experiments as configs under configs/experiment/. Apply codes HY-ENTRY, HY-STRUCT, HY-GROUP, HY-PATH, HY-EXP, HY-BEST.

Step 3 鈥?LightningModule / DataModule conventions (Cluster 2)

Load references/model_design.md (PyTorch Lightning contract + timm + OpenMMLab), then shape modules that:

• Separate model backbones from the system (LightningModule).
• Are self-contained: optimizer + scheduler live in configure_optimizers.
• Have explicit typed __init__ with sensible defaults (no opaque params).
• Follow the method order: __init__ 鈫?forward 鈫?training_step 鈫? validation 鈫?test 鈫?configure_optimizers 鈫?extra hooks.
• Keep forward() for inference only (never training logic).
• Use LightningDataModule for data; torchmetrics (separate instance per step), /-named metrics, sync_dist=True under DDP. Apply codes PL-SYS, PL-SELF, PL-INIT, PL-ORDER, PL-FWD, PL-DM, PL-METRIC, PL-DDP, PL-OPT, PL-HPARAM.

Step 4 鈥?Python style & naming (Google Python Style Guide)

Load references/scaffold_grammar.md (PYSTYLE section), then write code that:

• Uses snake_case for functions/vars, CapWords for classes, UPPER_CASE for constants; avoids l, I, O single-letter names (GP-NAME).
• Respects line length <= 80 (Google) unless the project sets 99 (Black/PL template override) (GP-LEN).
• Groups imports: stdlib, third-party, local; no wildcard imports (GP-IMP).
• Carries docstrings on every public module/class/function (GP-DOC).
• Carries type annotations on all signatures (GP-ANN/GP-TYPE).
• Avoids semicolons, bare except:, mutable default args, print for diagnostics (GP-SEMI/GP-EXC/GP-DEF/GP-PRINT).
• Guards executables with if __name__ == "__main__": (GP-MAIN). Use scripts/audit_style.py as a conformance gate (it checks a subset of these codes). The full rule registry lives in references/coordination.md.

Step 5 鈥?Build from zero (Scenario A)

Used when the target is empty or absent. The directory structure is a frozen skeleton — required directories and fixed-name files must be present, but you may add your own configs and files on top of it.

1. Load references/scaffold_grammar.md (section 1: the authoritative directory tree) and templates/project_skeleton/MANIFEST.md (the exact file list).
2. Copy the templates/project_skeleton/ tree into the target repo. Required directories and fixed-name files are mandatory (enforced as LHT-STRICT BLOCKER). Config-group stubs named project (e.g. configs/data/project.yaml, configs/model/project.yaml) are placeholders: the group directory only needs at least one config file, so replace them with your own named configs (e.g. configs/model/resnet.yaml) — no need to keep the literal project.yaml. Additional configs/files beyond the skeleton are permitted.
3. Do not overwrite existing user files; report exactly what was created and what was skipped.
4. Then continue with Steps 1鈥? as you write each new file, so the project conforms from the first commit.

No improvisation rule: the structure above is the single source of truth. Never "improve", simplify, or expand the layout. If a need seems to require a new directory, place the code under the existing role split (src/data, src/models, src/utils) instead of inventing one.

6. Sync .gitignore: run python scripts/sync_gitignore.py . so the ignore list reflects the freshly created layout (the script only maintains its auto-managed block and never touches hand-written rules).

Step 6 鈥?Tidy existing repo (Scenario B)

Used when the target already has code. Apply the conventions by restructuring, not just noting gaps:

1. Audit current state against the rule-code registry (run scripts/audit_style.py and/or reason from the references) to enumerate deviations per category (STRUCTURE / CONFIG / LIGHTNING / PYSTYLE).
2. Restructure: relocate files into src/data, src/models, src/utils, configs/<group>/; add missing root files and tests/.
3. Rewrite to conform: convert hardcoded args into Hydra _target_ configs; split model backbones from LightningModule systems; rename symbols per GP-NAME / PL-*; apply torchmetrics and /-named logging.
4. Preserve behavior 鈥?prefer moving/renaming over deleting; keep outputs identical.
5. Confirm: re-run scripts/audit_style.py; remaining BLOCKER/MAJOR items must be resolved before declaring the repo tidy.
6. Sync .gitignore: run python scripts/sync_gitignore.py . so the ignore list tracks the new/relocated directories (e.g. logs/, outputs/, wandb/, checkpoints/). The script derives entries from the current layout inside a marked auto-managed block; hand-written rules are preserved.

Step 7 鈥?Apply & confirm (both scenarios)

Write the code to match the convention. When a change touches two layers (e.g. a config that instantiates an untyped module), apply the single most specific code and follow the related code from the other reference (see references/coordination.md). If a conformance script is available, run it to confirm the change holds.

Step 8 鈥?Run the mandatory quality gate (both scenarios)

After writing/editing code, the project MUST pass the standard quality tools before the change is accepted. These are the lab's required checks; run them from the project root (configs live in pyproject.toml / .pre-commit-config.yaml):

black .                 # 1. Formatting (line-length 99 by default)
isort .                 # 2. Import ordering (black profile)
ruff check .            # 3. Static lint + import/style/complexity checks
mypy src/              # 4. Type checking across the source package
pytest tests/          # 5. Run the test suite (smoke + unit)

Rules:

• Run all five in order; do not skip any. Fix every error they report.
• black/isort may rewrite files 鈥?re-read them after, then re-run to confirm clean.

Caches are aggregated, not scattered

Tool caches and run artifacts that have no direct relation to the project code are swept into a single .cache/ folder at the repo root so the tree stays clean. This covers only caches (.mypy_cache/, .pytest_cache/, .ruff_cache/, .coverage, htmlcov/) 鈥?not Hydra run outputs, which stay at the root (logs/, outputs/, wandb/) as real experiment artifacts.

• Redirect caches with the provided helper: scripts/run_gate.sh (bash) or scripts/run_gate.ps1 (PowerShell). It sets MYPY_CACHE_DIR, PYTEST_DEBUG_TEMPROOT, COVERAGE_FILE and ruff --cache-dir, then runs the five tools; with SWEEP_ONLY=1 it only moves loose caches into .cache/.
• All .cache/ contents are already covered by .gitignore, so they are never committed. See .cache/README.md.
• mypy src/ must reach zero type errors (strict optional; at minimum no untyped public signatures 鈥?see GP-ANN).
• pytest tests/ must be green; add/extend a smoke test for any new LightningModule/DataModule/entrypoint.
• In CI this exact sequence runs as the gate; locally it is the same contract.

Step 9 鈥?Apply the Rule Cards (cross-cutting, both scenarios)

Beyond the four core code categories, the skill enforces seven standard families as Rule Cards (RC-*) 鈥?abstracted, machine-checkable rules rather than mere links. They live inside the four cluster files. Load references/rule_cards.md (index) plus the cluster file for the concern:

• Cluster 3 鈥?Experiment Reproducibility (references/experiment_repro.md):
  • Hydra Config-First RC-HYDRA-*: every experimental variable (lr, batch, seed, paths, ...) exists in config, read from cfg; no hardcoded literals like lr = 0.001.
  • FAIR data RC-DATA-*: datasets have metadata, identifier, version pinned to a tag, a runnable loader; every run records its data version.
  • Versioning / Git Flow RC-VER-*: every experiment release is a git tag following SemVer; work stays on feature/*/experiment/*, not main.
  • Meta Research philosophy RC-META-*: reproducible/configurable/ documented/benchmarkable experiments; no train_v2_final.py, variants as experiment configs.
• Cluster 2 鈥?Model & Component Design (references/model_design.md):
  • timm model design RC-TIMM-*: name the architecture (e.g. VisionTransformer, not MyModel); ops in models/layers/, blocks in models/blocks/, named models in models/architectures/; register via factory.
  • OpenMMLab Registry RC-OPENMMLAB-*: register components with @X.register_module(); build via build_from_cfg(cfg); never if model == "vit" branching.
• Cluster 4 鈥?Engineering Process (references/engineering_process.md):
  • Engineering (Google) RC-ENG-*: small reviewable changes, documented public API, test coverage, review before merge to main; interface docs never drift (RC-ENG-007).
  • Scientific Python RC-SP-*: estimators expose fit(X,y)/predict(X); public symbols documented + typed; numeric code tested; installable package + CI.
  • Research Code Comment Standard COMMENT-*: comments explain why (intent, math, design decision, experiment constraint), not a line-by-line narration; public APIs/docstrings follow NumPy/PEP257; math carries the formula + citation; TODO(owner): reason; no stale comments (COMMENT-001..017).
  • LLM Coding-Discipline (Karpathy) RC-KARPATHY-*: a behavioral layer over the mechanical cards 鈥?Think Before Coding (surface assumptions, tradeoffs, confusion), Simplicity First (minimum code, no speculative abstraction), Surgical Changes (touch only what is asked, match style, clean only your own orphans), Goal-Driven Execution (imperative 鈫? verifiable goal + verify loop). It counters LLM failure modes 鈥?wrong assumptions, overcomplication, orthogonal edits, vague goals 鈥?and biases toward caution over speed (use judgment on trivial one-liners).

When a Rule Card touches code already covered by LHT-/HY-/PL-/GP-*, apply the single most specific code and cross-link; never duplicate a rule under two codes.

Mandatory quality tools

These five tools are required for every research project governed by this skill. They operationalize the conventions: black/isort enforce formatting (GP-LEN/GP-IMP), ruff enforces static rules (GP-SEM*/GP-EXC/...), mypy enforces typing (GP-ANN/GP-TYPE), and pytest enforces that the code actually runs. Their configs ship with the scaffold template.

Tool	Purpose	Invocation
black	Formatting	black .
isort	Import ordering	isort .
ruff	Static analysis / lint	ruff check .
mypy	Type checking	mypy src/
pytest	Tests	pytest tests/

Output Format

This skill does not emit a review report by default. It shapes the code it writes. When you must explain a convention choice to the user, return a short fixed Markdown note:

# Convention applied: <operation> in <target>

## Decision
- <what structure/naming/config pattern was applied>

## Rule
- <code> 鈥?<one-line rule from the registry>

## Note
- <optional: deliberate deviation or ambiguity resolved>

Codes are the unified registry in references/coordination.md: STRUCTURE (LHT-*), CONFIG (HY-*), LIGHTNING (PL-*), PYSTYLE (GP-*). Severity is used only when a script is run: BLOCKER (breaks run/repro), MAJOR (core rule), MINOR (style nit).

Error Handling

• No Python/config target found: ask the user for the path, or build from zero (Scenario A, Step 5).
• Conformance script missing deps: print pip install -r requirements.txt, retry once; if still failing, fall back to manual convention checks.
• Permission denied on Write: stop, explain what could not be written, and suggest the user grant access.
• Unparseable file: skip it, note the reason, and continue the rest.
• Target not empty but Scenario A requested: switch to Scenario B (tidy) 鈥? never overwrite; restructure and add missing files, reporting conflicts.
• Reference file missing/unreadable: load the next applicable reference; if none, fall back to the inlined rules here and flag the gap.
• Ambiguous rule: prefer the project's own pyproject.toml/setup.cfg config over the generic default, and note the override applied.

Constraints

• Architecture is invariant: the project's fixed structure is the stable base. Never break it, bypass it, or replace it with a different layout while coding. Add and change code within the architecture; keep it clear.
• Single responsibility: this skill ONLY governs research-code standards (architecture, naming, structure, configs); do not mix in unrelated tasks.
• It is a contextual enforcer, not a post-hoc reviewer: apply conventions as code is written/edited, not after.
• Two axes only: (1) project-level architecture, (2) code-level naming/format/ calling. Keep both uniform; do not introduce a third, ad-hoc concern.
• Never auto-commit or push changes unless the user explicitly asks.
• Never invent config values or names; derive them from the conventions and existing project patterns.
• Respect the project's existing line-length / formatter config if present.
• Load reference docs lazily: read references/ files only for the concern being acted on, not all at once.
• Use the unified rule-code registry in references/coordination.md; never invent a code not in the registry, and never apply one rule under two codes.