Skip to content
  1. Skills at a glance
  2. Build and clean up
  3. /pstack:tdd

/pstack:tdd

Call when needed

In one lineWrites a failing test first, then fixes the code, then runs the test again to see it pass.

When to use
Fixing a bug, when tests are easy to run on your machine.
Say it like this
/pstack:tdd implement

Just asking vs. using it

The same request, typed plainly or with /pstack:tdd. Here's what changes.

Just askingWith /pstack:tdd
Edits the code and just says it's fixed.Writes a test first and confirms it fails because of this bug.
Changes the test to match the wrong code.Writes the test from intended behavior and keeps existing assertions intact.
Forces in a test made mostly of mocks.Uses a script or repro command when a test is impractical, and says why.

What the document says

4 sections, about 450 words, 2 min to read. Click a section to read it.

OpeningIt says that with a cheap test path, the AI writes a test that fails before the fix and passes after. Otherwise it uses the closest check.

  1. 1WorkflowSix steps: understand the bug, pick the nearest test type, write a failing test, confirm why it fails, fix minimally, rerun.
  2. 2If a Failing Test Is ImpracticalFalls back to a targeted script, repro command or browser automation. No new test beats a bad one.
  3. 3GuardrailsTests encode intended behavior, assertions stay, focus stays on this bug, and flaky bugs get deterministic tests where possible.
  4. 4Final ResponseReports evidence: the test that failed before and its error, the passing run after, or why that wasn't possible.

See the wording worth borrowingRead the full text

Wording worth borrowing

A few sentences from the original: what each one makes the AI do, why it works, and how you can borrow it.

  1. Check why it fails, too

    Confirm it fails for the intended reason.

    Makes the AI
    Once the new test goes red, it checks the red is this bug, not a typo or a missing dependency.
    Why it works
    "Make it fail first" lets any red light pass; "fail for the right reason" is what makes the step prove something.
    Borrow it
    When the AI reproduces a problem, add: "Once it fails, tell me whether the error is the same one I described."
  2. Allow "skip it this time"

    Prefer no new test over a bad test.

    Makes the AI
    When a test is hard to write it verifies another way and says why, instead of forcing in a test of mocks.
    Why it works
    Rigid steps push an AI to fill them with junk; saying skipping is allowed, and defining bad, lets it stop.
    Borrow it
    Leave an exit in fixed steps: "If no image fits, leave it blank and mark it; don't use an unrelated one."
  3. Say what's the reference

    The test should encode intended behavior, not mirror the current implementation.

    Makes the AI
    Its tests check what the feature should do, not a copy of today's buggy code.
    Why it works
    The nearest reference an AI has is the current code; naming "intended behavior" stops it from treating wrong as right.
    Borrow it
    When the AI checks work, say what to trust: "Go by the original contract, not the last translation."
  4. List what a report must carry

    Report the evidence, not just the outcome:

    Makes the AI
    At the end it tells you which test failed before, how, and which run passed after.
    Why it works
    Asked for an outcome, the AI says "fixed"; listing the evidence it must bring lets you judge without follow-ups.
    Borrow it
    When you ask for a report, list it: "Which file changed, how you tested, and the last lines of test output."

Full text

The SKILL.md the AI reads, as written.

descriptionUse only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested.

TDD Bug Fix

When fixing a bug with a clear, cheap test path, make the broken behavior executable before changing production code. The goal is a focused regression test that fails before the fix and passes after it.

Do not force a test when it would be impractical. If the available test would require broad harness setup, brittle mocks, slow end-to-end infrastructure, production-only state, vague reproduction steps, or large unrelated fixture churn, skip adding a new test and use the closest useful verification instead.

Workflow

  1. Understand the bug. Identify the intended behavior, current behavior, affected path, and smallest observable reproduction.
  2. Choose the narrowest executable check. Prefer the closest unit, component, integration, or regression test already used for that codepath. If no practical test path is obvious, do not create one from scratch just to satisfy the workflow.
  3. Write the failing test first. Add the smallest focused test that would have caught the bug. The test should encode intended behavior, not mirror the current implementation.
  4. Run the new test before fixing. Confirm it fails for the intended reason. If it passes or fails for an unrelated reason, correct the test or reproduction before editing the implementation.
  5. Fix the bug. Make the smallest production change that satisfies the intended behavior while preserving nearby contracts.
  6. Rerun the regression test. Confirm the test now passes.

If a Failing Test Is Impractical

Use the closest executable regression check instead: a targeted script, manual reproduction command, browser automation, snapshot comparison, log assertion, or focused integration check.

Prefer no new test over a bad test. A bad test is one that mostly tests mocks, encodes current implementation details, depends on timing or unrelated global state, needs expensive infrastructure for a small fix, or would be deleted immediately after proving the fix.

Guardrails

  • Do not change tests merely to match a wrong implementation.
  • Do not weaken existing assertions unless the expected behavior has genuinely changed and the reason is clear.
  • Keep the regression test focused on the bug. Avoid broad fixture churn or unrelated coverage expansion.
  • If the bug is flaky, make the test deterministic where possible and document the signal being locked down.
  • If the bug exposes a broader class of failures, first land the focused regression path, then consider additional sibling coverage.

Final Response

Report the evidence, not just the outcome:

  • Name the failing-before test or executable check and the failure it produced.
  • Name the passing-after test run and any nearby validation performed.
  • If failing-before evidence could not be demonstrated, state why and describe the closest regression check used instead.

Original by Lauren Tan (poteto), MIT license. Checked against the pstack mirror at 97de40d. View on GitHub

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.