investigation_skill

Overview

This skill scaffolds structured investigations for empirical research and documentation inside the project's scratch area. It creates a dated investigation folder, organizes notes and artifacts, and guides tracing, bug hunting, feasibility tests, and design research for multi-animal pose-tracking systems.

How this skill works

When you start an investigation, the skill creates a dated folder under scratch/ and initializes a short task summary and checklist file to drive the work. It suggests concrete exploration patterns (tracing, archeology, bug reproduction, technical proofs, design research), generates small exploratory scripts, and organizes findings into subdocuments and artifacts as patterns emerge.

When to use it

• You want to trace data or call flow ("trace from X to Y", "what touches X").
• You need a comprehensive system archeology or documentation of an entry-to-exit flow.
• You must reproduce and root-cause a bug across components or repos.
• You want to test feasibility with quick proofs-of-concept (can we do X?).
• You are exploring API alternatives, design trade-offs, or system constraints.
• You need to gather context and artifacts before drafting a PR-level change.

Best practices

• Create a dated investigation folder under scratch/ (scratch is gitignored) to hold scripts, notes, and artifacts; treat everything there as temporary working material.
• Start with a concise task description, background, and a checked checklist to capture reproducible steps and goals.
• Write small, focused scripts to exercise local code paths; use uv for standalone experiments and the project python for scripts that import project modules.
• Split long investigations into numbered subdocuments as distinct concerns emerge (e.g., CLI, data flow, model IO).
• Capture reproducible commands, failing inputs, logs, and minimal repros so fixes can be embedded directly into PRs.
• Include visual artifacts (plots, screenshots) and reference them from notes for architecture and design decisions.

Example use cases

• Trace how tracked pose data flows from acquisition to model input and to output serialization to identify coupling points.
• Reproduce a sporadic tracking failure, trace its stack/dataflow, and produce a minimal script demonstrating the bug.
• Run feasibility tests for a proposed API change by implementing a quick proof-of-concept in scratch and documenting limitations.
• Document the full inference pipeline across components to create a maintainable reference for new contributors.
• Compare alternate design approaches for multi-animal identity tracking and record trade-offs with example artifacts.