# investigation

Adopt this skill: https://proskills.md/skills/other/talmolab-sleap-claude-skills-investigation

Page: https://proskills.md/skills/other/talmolab-sleap-claude-skills-investigation
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude/skills/investigation/SKILL.md
size: 3671
sha: b1d47fcec2b8ebaca18c9135701a43b8d9d6345e
upstream: https://github.com/talmolab/sleap/blob/develop/.claude/skills/investigation/SKILL.md

````text
---
name: investigation
description: >
  Scaffolds a structured investigation in scratch/ for empirical research and documentation.
  Use when the user says "start an investigation" or wants to: trace code paths or data flow
  ("trace from X to Y", "what touches X", "follow the wiring"), document system architecture
  comprehensively ("document how the system works", "archeology"), investigate bugs
  ("figure out why X happens"), explore technical feasibility ("can we do X?"), or explore
  design options ("explore the API", "gather context", "design alternatives").
  Creates dated folder with README. NOT for simple code questions or single-file searches.
---

# Set up an investigation

## Instructions

1. Create a folder in `{REPO_ROOT}/scratch/` with the format `{YYYY-MM-DD}-{descriptive-name}`:
   ```bash
   mkdir scratch/$(uv run python -c "import datetime; print(datetime.date.today().isoformat())")-{descriptive-name}
   ```
2. Create a `README.md` in this folder with: task description, background context, task checklist. Update with findings as you progress.
3. Create scripts and data files as needed for empirical work.
4. For complex investigations, split into sub-documents as patterns emerge.

## Investigation Patterns

These are common patterns, not rigid categories. Most investigations blend multiple patterns.

**Tracing** - "trace from X to Y", "what touches X", "follow the wiring"
- Follow call stack or data flow from a focal component to its connections
- Can trace forward (X → where does it go?) or backward (what leads to X?)
- Useful for: assessing impact of changes, understanding coupling

**System Architecture Archeology** - "document how the system works", "archeology"
- Comprehensive documentation of an entire system or flow for reusable reference
- Start from entry points, trace through all layers, document relationships exhaustively
- For complex systems, consider numbered sub-documents (01-cli.md, 02-data.md, etc.)

**Bug Investigation** - "figure out why X happens", "this is broken"
- Reproduce → trace root cause → propose fix
- For cross-repo bugs, consider per-repo task breakdowns

**Technical Exploration** - "can we do X?", "is this possible?", "figure out how to"
- Feasibility testing with proof-of-concept scripts
- Document what works AND what doesn't

**Design Research** - "explore the API", "gather context", "design alternatives"
- Understand systems and constraints before building
- Compare alternatives, document trade-offs
- Include visual artifacts (mockups, screenshots) when relevant
- For iterative decisions, use numbered "Design Questions" (DQ1, DQ2...) to structure review

## Best Practices

- Use `uv` with inline dependencies for standalone scripts; for scripts importing local project code, use `python` directly (or `uv run python` if env not activated)
- Use subagents for parallel exploration to save context
- Write small scripts to explore APIs interactively
- Generate figures/diagrams and reference inline in markdown
- For web servers: `npx serve -p 8080 --cors --no-clipboard &`
- For screenshots: use Playwright MCP for web, Qt's grab() for GUI
- For external package API review: clone to `scratch/repos/` for direct source access

## Important: Scratch is Gitignored

The `scratch/` directory is in `.gitignore` and will NOT be committed.

- NEVER delete anything from scratch - it doesn't need cleanup
- When distilling findings into PRs, include all relevant info inline
- Copy key findings, code, and data directly into PR descriptions
- PRs must be self-contained; don't reference scratch files
````

## File: README.md
upstream: https://github.com/talmolab/sleap/blob/develop/README.md

````text
[![CI](https://github.com/talmolab/sleap/actions/workflows/ci.yml/badge.svg)](https://github.com/talmolab/sleap/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/talmolab/sleap/branch/develop/graph/badge.svg?token=oBmTlGIQRn)](https://codecov.io/gh/talmolab/sleap)
[![Documentation](https://img.shields.io/badge/Documentation-sleap.ai-lightgrey)](https://docs.sleap.ai)
[![Downloads](https://static.pepy.tech/personalized-badge/sleap?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=PyPI%20Downloads)](https://pepy.tech/project/sleap)
[![Stable version](https://img.shields.io/github/v/release/talmolab/sleap?label=stable)](https://github.com/talmolab/sleap/releases/)
[![Latest version](https://img.shields.io/github/v/release/talmolab/sleap?include_prereleases&label=latest)](https://github.com/talmolab/sleap/releases/)

# Social LEAP Estimates Animal Poses (SLEAP)

![SLEAP Demo](https://raw.githubusercontent.com/talmolab/sleap/develop/docs/assets/images/sleap_movie.gif)

**SLEAP** is an open-source deep-learning based framework for multi-animal pose tracking [(Pereira et al., Nature Methods, 2022)](https://www.nature.com/articles/s41592-022-01426-1). It can be used to track any type or number of animals and includes an advanced labeling/training GUI for active learning and proofreading.

## Features

* Easy, one-line installation with support for all OSes
* Purpose-built GUI and human-in-the-loop workflow for rapidly labeling large datasets
* Single- and multi-animal pose estimation with *top-down* and *bottom-up* training strategies
* Customizable neural network architectures that deliver *accurate predictions* with *very few* labels
* Fast training: 15 to 60 mins on a single GPU for a typical dataset
* Fast inference: up to 600+ FPS for batch, <10ms latency for realtime
* Support for remote training/inference workflow (for using SLEAP without GPUs)
* Flexible developer API for building integrated apps and customization
* Two independent backends— [`sleap-nn`](https://nn.sleap.ai) and [`sleap-io`](https://io.sleap.ai) for training/inference pipelines & handling SLEAP files respectively

## Get some SLEAP

SLEAP is installed as a Python package. We strongly recommend using [uv](https://docs.astral.sh/uv/) to install SLEAP in its own environment.

You can find the latest version of SLEAP in the [Releases](https://github.com/talmolab/sleap/releases) page.

### Quick install

> **Python 3.14 is not yet supported**
>
> SLEAP currently supports **Python 3.11, 3.12, and 3.13**.  
> **Python 3.14 is not yet tested or supported.**  
> By default, `uv` will use your system-installed Python.  
> If you have Python 3.14 installed, you must specify the Python version (≤3.13) in the install command.  
>
> For example:
>
> ```bash
> uv tool install --python 3.13 "sleap[nn]"  ...
> ```
> Replace `...` with the rest of your install command as needed.

**`uv tool install` (any OS):**

First, install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) if you haven't already:

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Then install SLEAP:

```bash
# Windows/Linux CUDA 12.8
uv tool install "sleap[nn]" --index https://download.pytorch.org/whl/cu128 --index https://pypi.org/simple

# macOS / CPU-only
uv tool install "sleap[nn]" --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple
```

Run the SLEAP GUI after installation:

```bash
sleap
```

See the docs for [full installation instructions](https://docs.sleap.ai/latest/installation).

## Learn to SLEAP

- **Learn step-by-step:** [Tutorial](https://docs.sleap.ai/latest/tutorial/overview)
- **Learn more advanced usage:** [Guides](https://docs.sleap.ai/latest/guides/guides-overview/) and [Notebooks](https://docs.sleap.ai/latest/notebooks/notebooks-overview/)
- **Learn by watching:** [COSYNE 2024 Tutorial (Part 1)](https://youtu.be/R5PRhkhAve0), [COSYNE 2024 Tutorial (Part 2)](https://youtu.be/Z64v-vp-Jvo), [ABL:AOC 2023 Workshop](https://www.youtube.com/watch?v=BfW-HgeDfMI), and [MIT CBMM Tutorial](https://cbmm.mit.edu/video/decoding-animal-behavior-through-pose-tracking)
- **Learn by reading:** [Paper (Pereira et al., Nature Methods, 2022)](https://www.nature.com/articles/s41592-022-01426-1) and [Review on behavioral quantification (Pereira et al., Nature Neuroscience, 2020)](https://rdcu.be/caH3H)
- **Learn from others:** [Discussions on Github](https://github.com/talmolab/sleap/discussions)

## References

SLEAP is the successor to the single-animal pose estimation software [LEAP](https://github.com/talmo/leap) ([Pereira et al., Nature Methods, 2019](https://www.nature.com/articles/s41592-018-0234-5)).

If you use SLEAP in your research, please cite:

> T.D. Pereira, N. Tabris, A. Matsliah, D. M. Turner, J. Li, S. Ravindranath, E. S. Papadoyannis, E. Normand, D. S. Deutsch, Z. Y. Wang, G. C. McKenzie-Smith, C. C. Mitelut, M. D. Castro, J. D'Uva, M. Kislin, D. H. Sanes, S. D. Kocher, S. S-H, A. L. Falkner, J. W. Shaevitz, and M. Murthy. [Sleap: A deep learning system for multi-animal pose tracking](https://www.nature.com/articles/s41592-022-01426-1). *Nature Methods*, 19(4), 2022

**BibTeX:**

```bibtex
@ARTICLE{Pereira2022sleap,
   title={SLEAP: A deep learning system for multi-animal pose tracking},
   author={Pereira, Talmo D and 
      Tabris, Nathaniel and
      Matsliah, Arie and
      Turner, David M and
      Li, Junyu and
      Ravindranath, Shruthi and
      Papadoyannis, Eleni S and
      Normand, Edna and
      Deutsch, David S and
      Wang, Z. Yan and
      McKenzie-Smith, Grace C and
      Mitelut, Catalin C and
      Castro, Marielisa Diez and
      D'Uva, John and
      Kislin, Mikhail and
      Sanes, Dan H and
      Kocher, Sarah D and
      Samuel S-H and
      Falkner, Annegret L and
      Shaevitz, Joshua W and
      Murthy, Mala},
   journal={Nature Methods},
   volume={19},
   number={4},
   year={2022},
   publisher={Nature Publishing Group}
   }
}
```

**Technical issue with the software?**

1. Check the [Help page](https://docs.sleap.ai/latest/help).
2. Ask the community via [discussions on Github](https://github.com/talmolab/sleap/discussions).
3. Search the [issues on GitHub](https://github.com/talmolab/sleap/issues) or open a new one.

**General inquiries?**
Reach out to [talmo@salk.edu](mailto:talmo@salk.edu).

## Acknowledgments

SLEAP was created in the [Murthy](https://murthylab.princeton.edu) and [Shaevitz](https://shaevitzlab.princeton.edu) labs at the [Princeton Neuroscience Institute](https://pni.princeton.edu) at Princeton University.

SLEAP is currently being developed and maintained in the [Talmo Lab](https://talmolab.org) at the [Salk Institute for Biological Studies](https://salk.edu).

### Maintainers

* **Divya Murali** ([@gitttt-1234](https://github.com/gitttt-1234)), Salk Institute for Biological Studies
* **Amick Licup** ([@alicup29](https://github.com/alicup29)), Salk Institute for Biological Studies
* **Elizabeth Berrigan** ([@eberrigan](https://github.com/eberrigan)), Salk Institute for Biological Studies
* **Andrew Park** ([@7174Andy](https://github.com/7174Andy)), Salk Institute for Biological Studies
* **Tom Han** ([@tom21100227](https://github.com/tom21100227)), Salk Institute for Biological Studies
* **Talmo Pereira** ([@talmo](https://github.com/talmo)), Salk Institute for Biological Studies

### Contributors
SLEAP would not be possible without major contributions from many folks, including:

* **Liezl Maree**, Salk Institute for Biological Studies
* **Arlo Sheridan**, Salk Institute for Biological Studies
* **Arie Matsliah**, Princeton Neuroscience Institute, Princeton University
* **Nat Tabris**, Princeton Neuroscience Institute, Princeton University
* **David Turner**, Research Computing and Princeton Neuroscience Institute, Princeton University
* **Joshua S
````
