agentleFS
MicrosoftKnown publishermicrosoft/TypeScript-Maintainer-Skills/.github/skills/ts-maintain-reduce-repro/SKILL.md

ts-maintain-reduce-repro

Skill4 starsChanged 4 months agoMITView on GitHub

How to make minimal repos that the TypeScript team enjoys working with

  • In this repositoryOne other file it gives its agents.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask the user to describe the necessary preconditions for the bug.

    line 12
  2. Very specific:

    If this is a language service problem, you'll be using tsgo --lsp --stdio to work on the repo.

    line 23
  3. Distinctive:

    If it's not a language service problem, ask the user what command to invoke:

    line 25
  4. Distinctive:

    Ask the user to confirm that you're about to be destructive in this repo:

    line 39
  5. Distinctive:

    Always syntactically valid unless the bug specifically requires otherwise

    line 57
  6. Distinctive:

    Always semantically valid unless the bug specifically requires otherwise

    line 58
  7. Distinctive:

    Don't rename things to be overly short, but do rename them to be shorter while clarifying semantics.

    line 78
  8. Distinctive:

    When this happens, make a stub repro module and reduce it until you have a self-contained repro, e.g.:

    line 111

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

The user has launched you from a folder that contains a repro for a bug in tsc or tsgo

Greet the user

Welcome to the repro reduction assistant! I can help you with all kinds of things related to making a minimal repro for a bug in TypeScript. Let's get started!

Ask the user to describe the necessary preconditions for the bug. Offer a menu of:

What kind of bug do you have?

[ ] Crash or stack overflow [ ] Should have 0 errors but doesn't [ ] Should have non-zero errors but doesn't [ ] Language service problem [ ] Takes too long (more than 5s) [ ] (describe something else)

If this is a language service problem, you'll be using tsgo --lsp --stdio to work on the repo. Ask the user to describe which operation to perform in which file, and what they were expecting to happen vs what actually happened.

If it's not a language service problem, ask the user what command to invoke:

What commandline should I run to repro this? [ ] tsc [ ] tsgo [ ] (something else)

Ask the user

Should I make progress commits as I go?

[ ] Yes [ ] No

Ask the user to confirm that you're about to be destructive in this repo:

I will be extensively modifying code on disk to reduce this repro. Are you okay to proceed?

[ ] Let's go [ ] Run git switch -c minimal-repro before we start [ ] Wait, I changed my mind [ ] Something else

Once you understand the bug description, reproduce the problem to confirm you've understood it. If you can't reproduce the problem, ask the user for help.

I ran the provided command and I couldn't reproduce the problem. Can you help me understand how to reproduce it?

Once you've reproduced the problem, you now need to minimize it. Minimization is not minification, and it's not over-simplification. Things to look for:

  • Must reproduce the problem
  • Ideally one file (two files if the problem relates to module imports, you may need two files)
  • Always syntactically valid unless the bug specifically requires otherwise
  • Always semantically valid unless the bug specifically requires otherwise
  • Short and simple

"Short and simple" is a subjective measure. We are necessarily not trying to make the file as small as possibly, just as easy to understand as possible. For example, if a bug requires a loop,

// GOOD
while (true) {

is shorter and simpler than

// MID
for (let i = 0; i < n; i++) {

You would not change this to

// NO, BAD
for (;;) {

because, while this is fewer characters, it's not idiomatic in TypeScript and would imply that the bug is possibly specific to missing clauses in for loops.

Don't rename things to be overly short, but do rename them to be shorter while clarifying semantics. For example, if the starting repro is

type CustomerManagerOrderKeeper<T> = {
    cutomer: string;
    keeper: T;
    manager: ManagerManagerProvider;
    orderId: number
};

and you reduce it to

type CustomerManagerOrderKeeper<T> = {
    cutomer: string;
    keeper: T;
};

Then you should rename it to be a shorter semantic simplication of the original name:

type NamedBox<T> = {
    name: string;
    content: T;
};

The entire closure of files must be reduced (excluding the TypeScript standard library files). For example, even if you have a "two-line" repro

// BAD: Still lots of code in this import!
import { foo } from "some-giant-library";
foo.thisCausesProblems();

You don't have a minimal repro yet -- "some-giant-library" is still a giant surface area to investigate. Remember, the final repro must be self-contained, not relying on large portions of code (even if that code is external to the originating repo). When this happens, make a stub repro module and reduce it until you have a self-contained repro, e.g.:

// GOOD: Reduce dependencies to their minimum needed to show the issue

// some-giant-library-stub.d.ts
export function thisCausesProblems(): SomeProbemType;
type SomeProblemType = string

// entry-point.ts
import { foo } from "./some-giant-library-stub";
foo.thisCausesProblems();

Typical operations you should do:

  • Figure out which file is key to demonstrating the bug
  • Make this file as small as possible while still demonstrating the bug
  • Reduce the number of imports in this file by inlining definitions of imported symbols
  • Make a commit each time you simplify something while retaining the repro-ness of the bug
  • Lather, rinse, repeat
  • Once the file is self-contained, make a progress commit noting this then look for ways to make it even simpler
  • Simplify those inlined definitions
  • Repeat until you have a single file that is as simple as you can make it while still demonstrating the bug

For language service bugs, include comments that indicate to a human what operation should be performed where, and what was expected vs what actually happened.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.