tessl-skills

Personal Tessl agent skills for James Stainer — general programming discipline, useful in any codebase or language.

Skills

reproduce-first-debugging

An evidence-gated debugging pipeline for coding agents. The failure mode it prevents: an agent reads the stack trace, edits the "obvious" file, and declares victory over a bug it never actually saw happen. With the skill loaded, every step leaves an auditable artifact in the transcript:

• The Iron Rule — no source edits until one command reproduces the failure (deterministically, or with a measured failure rate for flakes) and its output is pasted, observed vs expected.
• Baseline first — record the pre-existing test failures before touching anything, so new breakage can't hide among old.
• Hypothesis loop, capped at 3 — each hypothesis is one falsifiable sentence confirmed by an experiment, never by code-reading; after three refutations, stop guessing and bisect.
• Bisect toolbox — git bisect run with correct exit-code semantics (125 = skip, ≥128 aborts, wrapper included), plus input and code-path bisection for non-git trees.
• Root cause over symptom — a patch-smell list (bare excepts, None-guards, sleep/retry, test-weakening) that forces an honest MITIGATION label instead of "fixed".
• Fix protocol — regression test red → minimal fix → green → exact repro re-run → baseline re-run → sibling-bug grep → scope audit.
• Closing report — a fixed 7-field template (Status / Repro / Root cause / Fix / Regression / Suite / Siblings) that degrades honestly to UNVERIFIED when the bug can't be reproduced.

Install

tessl install github:james-stainer/tessl-skills --skill reproduce-first-debugging

Note: Tessl's install policy requires the explicit --skill flag for GitHub sources.

Validate

tessl skill lint .

Expansion roadmap

This repo is meant to grow. Natural next steps:

1. references/repro-recipes.md — per-ecosystem reproduction harness templates (pytest -x -k, jest -t, go test -run, docker-pinned environments).
2. references/flaky-tests.md — a deeper flake-triage sub-procedure: seed/time/ordering/isolation matrix, stress loops, quarantine policy.
3. references/minimization.md — shrinking failing inputs: delta debugging, hypothesis shrinking, creduce.
4. references/no-local-repro.md — the production/log-only variant when the failure can't be reproduced locally.
5. A repro-gate hook — a PreToolUse hook that blocks file edits until a reproduction note exists, turning the discipline into an enforced gate rather than an instruction.
6. Sibling skills from the same design bench: measure-before-optimizing (baseline → profile → one change → re-measure → keep or revert), pin-before-change (characterization tests before refactoring legacy code), git-surgery (safe history recovery), codebase-recon (fast orientation in an unfamiliar repo).

Add a new skill by creating skills/<name>/SKILL.md; tessl skill lint validates the structure.