talmolab
diff --git a/‎.claude/skills/investigation/SKILL.md‎
Lines changed: 67 additions & 0 deletions b/‎.claude/skills/investigation/SKILL.md‎
Lines changed: 67 additions & 0 deletions
diff --git a/‎.claude/skills/qt-testing/SKILL.md‎
Lines changed: 82 additions & 0 deletions b/‎.claude/skills/qt-testing/SKILL.md‎
Lines changed: 82 additions & 0 deletions
diff --git a/‎.claude/skills/qt-testing/scripts/qt_capture.py‎
Lines changed: 131 additions & 0 deletions b/‎.claude/skills/qt-testing/scripts/qt_capture.py‎
Lines changed: 131 additions & 0 deletions
diff --git a/‎.github/workflows/build.yml‎
Lines changed: 56 additions & 0 deletions b/‎.github/workflows/build.yml‎
Lines changed: 56 additions & 0 deletions
@@ -0,0 +1,67 @@
+---
+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}`.
+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
@@ -0,0 +1,82 @@
+---
+name: qt-testing
+description: Capture and visually inspect Qt GUI widgets using screenshots. Use when asked to verify GUI rendering, test widget appearance, check layouts, or visually inspect any PySide6/Qt component. Enables Claude to "see" Qt interfaces by capturing offscreen screenshots and analyzing them with vision.
+---
+
+# Qt GUI Testing
+
+Capture screenshots of Qt widgets for visual inspection without displaying windows on screen.
+
+## Quick Start
+
+```python
+# Capture any widget
+from scripts.qt_capture import capture_widget
+path = capture_widget(my_widget, "description_here")
+# Then read the screenshot with the Read tool
+```
+
+## Core Script
+
+Run `scripts/qt_capture.py` or import `capture_widget` from it:
+
+```bash
+# Standalone test
+uv run --with PySide6 python .claude/skills/qt-testing/scripts/qt_capture.py
+```
+
+## Output Location
+
+All screenshots save to: `scratch/.qt-screenshots/`
+
+Naming: `{YYYY-MM-DD.HH-MM-SS}_{description}.png`
+
+## Workflow
+
+1. Create/obtain the widget to test
+2. Call `capture_widget(widget, "description")`
+3. Read the saved screenshot with the Read tool
+4. Analyze with vision to verify correctness
+
+## Interaction Pattern
+
+To interact with widgets (click buttons, etc.):
+
+```python
+# Find widget at coordinates (from vision analysis)
+target = widget.childAt(x, y)
+
+# Trigger it directly (not mouse events)
+if hasattr(target, 'click'):
+    target.click()
+    QApplication.processEvents()
+
+# Capture result
+capture_widget(widget, "after_click")
+```
+
+## Example: Test a Dialog
+
+```python
+import sys
+from PySide6.QtWidgets import QApplication
+from sleap.gui.learning.dialog import TrainingEditorDialog
+
+# Add skill scripts to path
+sys.path.insert(0, ".claude/skills/qt-testing")
+from scripts.qt_capture import capture_widget, init_qt
+
+app = init_qt()
+dialog = TrainingEditorDialog()
+path = capture_widget(dialog, "training_dialog")
+dialog.close()
+print(f"Inspect: {path}")
+```
+
+## Key Points
+
+- Uses `Qt.WA_DontShowOnScreen` - no window popup
+- Renders identically to on-screen display (verified)
+- Call `processEvents()` after interactions before capture
+- Use `childAt(x, y)` to map vision coordinates to widgets
+- Direct method calls (`.click()`) work; simulated mouse events don't
@@ -0,0 +1,131 @@
+#!/usr/bin/env python
+"""Qt widget screenshot capture utility.
+
+Captures screenshots of Qt widgets without displaying them on screen.
+"""
+
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from PySide6.QtWidgets import QApplication, QWidget
+from PySide6.QtCore import Qt
+
+# Output directory
+OUTPUT_DIR = Path("scratch/.qt-screenshots")
+
+
+def init_qt() -> QApplication:
+    """Initialize Qt application (required once per process)."""
+    app = QApplication.instance()
+    if app is None:
+        app = QApplication(sys.argv)
+    return app
+
+
+def timestamp() -> str:
+    """Generate timestamp for filename."""
+    return datetime.now().strftime("%Y-%m-%d.%H-%M-%S")
+
+
+def capture_widget(
+    widget: QWidget,
+    description: str,
+    output_dir: Optional[Path] = None,
+) -> Path:
+    """
+    Capture a screenshot of a widget without displaying it on screen.
+
+    Args:
+        widget: The QWidget to capture
+        description: Short description for filename (use underscores, no spaces)
+        output_dir: Override output directory (default: scratch/.qt-screenshots)
+
+    Returns:
+        Path to saved screenshot
+    """
+    out = output_dir or OUTPUT_DIR
+    out.mkdir(parents=True, exist_ok=True)
+
+    # Configure for invisible rendering
+    widget.setAttribute(Qt.WA_DontShowOnScreen, True)
+    widget.show()
+    QApplication.processEvents()
+
+    # Capture
+    pixmap = widget.grab()
+    if pixmap.isNull():
+        raise RuntimeError("Failed to capture widget - pixmap is null")
+
+    # Save with timestamp
+    desc_clean = description.replace(" ", "_").replace("/", "-")
+    filename = f"{timestamp()}_{desc_clean}.png"
+    filepath = out / filename
+
+    if not pixmap.save(str(filepath)):
+        raise RuntimeError(f"Failed to save screenshot to {filepath}")
+
+    # Don't close - caller may want to interact further
+    widget.hide()
+
+    return filepath
+
+
+def capture_and_click(
+    widget: QWidget,
+    x: int,
+    y: int,
+    description: str,
+) -> tuple[Path, Optional[QWidget]]:
+    """
+    Click at coordinates and capture the result.
+
+    Args:
+        widget: Parent widget
+        x, y: Coordinates to click (in widget coordinate space)
+        description: Description for filename
+
+    Returns:
+        Tuple of (screenshot path, clicked widget or None)
+    """
+    widget.setAttribute(Qt.WA_DontShowOnScreen, True)
+    widget.show()
+    QApplication.processEvents()
+
+    # Find and click widget at coordinates
+    target = widget.childAt(x, y)
+    if target is not None:
+        if hasattr(target, "click"):
+            target.click()
+        elif hasattr(target, "toggle"):
+            target.toggle()
+        QApplication.processEvents()
+
+    # Capture result
+    path = capture_widget(widget, description)
+    return path, target
+
+
+# Self-test when run directly
+if __name__ == "__main__":
+    from PySide6.QtWidgets import QPushButton, QVBoxLayout, QLabel
+
+    app = init_qt()
+
+    # Create test widget
+    widget = QWidget()
+    widget.setWindowTitle("Qt Capture Test")
+    widget.setFixedSize(300, 150)
+
+    layout = QVBoxLayout(widget)
+    layout.addWidget(QLabel("Qt Capture Test Widget"))
+    btn = QPushButton("Test Button")
+    layout.addWidget(btn)
+
+    # Capture it
+    path = capture_widget(widget, "self_test")
+    print(f"Captured: {path}")
+
+    widget.close()
+    print("Self-test complete!")
@@ -0,0 +1,56 @@
+name: Build and publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Publish to TestPyPI instead of PyPI"
+        required: false
+        default: "false"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Publish to TestPyPI
+        if: ${{ github.event.inputs.testpypi == 'true' }}
+        run: uv publish --index testpypi --trusted-publishing always
+
+      - name: Publish to PyPI
+        if: ${{ github.event.inputs.testpypi != 'true' }}
+        run: uv publish --trusted-publishing always