superpowers

Superpowers DL

English | 简体中文

Deep learning research workflows for agentic coding tools.

superpowers_DL is a research-focused fork of the original Superpowers project. The upstream project is strong for general software engineering. This fork is for model work: define a hypothesis, design the smallest falsifiable experiment, execute it with provenance, debug failures, analyze evidence, and only then claim an improvement.

Why This Fork Exists

Most deep learning iteration breaks down for process reasons, not typing speed:

• code changes start before the hypothesis, baseline, and metric are fixed
• multiple variables get changed in the same experiment pass
• training failures get "fixed" by folklore instead of root-cause isolation
• single lucky runs get treated as established results
• configs, seeds, commits, and artifacts go missing when results need to be shared

superpowers_DL turns those failure points into explicit skills and guardrails.

Who It Is For

Use this fork if your work looks like:

• paper reproduction
• architecture, loss, augmentation, or schedule changes
• training-debugging and experiment triage
• baseline and ablation comparison
• reproducibility checks before sharing numbers

If you mainly need generic product-engineering workflows, use upstream Superpowers instead.

What Changed From Upstream

• Software-engineering workflow skills were removed.
• The repository was rebuilt around deep learning experiment design, execution, debugging, interpretation, and reproducibility.
• Installation examples in this repository point to this fork, not the upstream obra/superpowers repository.

Research Workflow

This fork is organized around a repeatable research loop:

flowchart TD
  A[Paper idea or model change] --> B[paper-to-implementation]
  B --> C[experiment-design]
  C --> D[experiment-planning]
  D --> E[experiment-worktree]
  E --> F[experiment-execution]
  F --> G{Training or run issue?}
  G -- Yes --> H[training-debugging]
  H --> F
  G -- No --> I[result-analysis]
  I --> J[experiment-closeout]
  J --> K[finishing-experiment-branch]
  K --> L[reproducibility-check]
  L --> M[Share claim or plan next experiment]

1. paper-to-implementation Translate a paper idea into the smallest faithful local experiment.
2. experiment-design Lock the hypothesis, baseline, metric, dataset assumptions, and compute budget before coding.
3. experiment-planning Turn the design into concrete code changes, sanity checks, runs, and artifact capture.
4. experiment-worktree Create an isolated git worktree so experiment code changes do not affect the main branch.
5. experiment-execution Execute the plan while keeping changes controlled and provenance intact.
6. training-debugging Handle NaNs, divergence, OOMs, inconsistent metrics, and other failures systematically.
7. result-analysis Decide what the evidence supports across baselines, ablations, and reruns.
8. experiment-closeout Make an explicit keep-or-revert decision after the run.
9. finishing-experiment-branch Handle the git mechanics of merging, pushing, pausing, or discarding the experiment branch.
10. reproducibility-check Verify the command, config, seeds, commit, dataset version, artifacts, and metric table before making a claim.

using-superpowers is injected at session start on supported platforms so research tasks route into the right workflow early.

Included Skills

Skill	Purpose
paper-to-implementation	Separate a paper's core intervention from hidden assumptions and map it into local code.
experiment-design	Convert a rough idea into a falsifiable experiment card.
experiment-planning	Produce an execution plan with exact files, commands, checks, and saved artifacts.
experiment-worktree	Create an isolated git worktree before experiment changes.
experiment-execution	Implement and run the smallest decisive experiment first.
training-debugging	Isolate and prove the root cause of training failures.
result-analysis	Compare baselines and reruns conservatively and decide next actions.
experiment-closeout	Decide whether experiment-specific code should stay or be reverted.
finishing-experiment-branch	Merge, push, pause, or discard an experiment branch and clean up the worktree.
reproducibility-check	Gate performance claims on attached evidence.
using-superpowers	Enforce skill-first behavior at the start of a session.

Quick Start

Install the fork into your agent environment, then describe the research task naturally.

Example prompts:

• "I want to try rotary embeddings in this model."
• "Training goes to NaN after warmup."
• "Compare these ablations and tell me what to run next."
• "Help me reproduce this paper fairly."
• "I changed the loss and validation improved once. What evidence do I still need?"