Turn One Failing Test into a Bounded Agent Request

A failing test gives a coding agent a useful starting point when you supply the exact input, the assertion, the relevant implementation, and the requirement that makes the expected result correct. Ask the agent to check whether the implementation or the assertion disagrees with that requirement before changing either one.

Python's unittest documentation for Python 3.13 describes test cases as checks for a particular response to particular inputs. Its assertEqual method checks equality between two values. The assertion tells you what the test expects; your requirement source tells you whether that expectation is justified.

Put the requirement beside the failing case

This article uses a fictional booking-display function. The requirement, files, inputs, and tests are original teaching examples. The selected teaching runtime is Python 3.13. No example has been executed, and the article contains no captured failure or passing-test output.

The supplied product note, AV-2, says:

remaining_slots(capacity, booked) returns the number of places still open.
Inputs in scope are non-negative integers.
If booked is less than capacity, return capacity minus booked.
If booked equals or exceeds capacity, return zero.
This is a display calculation, not permission to create a booking.

The implementation in availability.py is:

def remaining_slots(capacity, booked):
    return max(capacity - booked, 1)

The relevant test in tests/test_availability.py is:

import unittest
from availability import remaining_slots


class AvailabilityTests(unittest.TestCase):
    def test_full_capacity_has_no_open_places(self):
        self.assertEqual(remaining_slots(4, 4), 0)

By manual calculation, capacity - booked is zero for (4, 4), and the shown function chooses the greater of zero and one. It should therefore return one, while the assertion expects zero. That is a predicted assertion failure, not a recorded run.

Here the test's expectation agrees with AV-2. The implementation's lower bound of one is the specific disagreement to investigate. The request can point to that boundary without authorizing changes to booking creation, storage, or the surrounding interface.

Follow the requirement through both branches

A red test does not, by itself, decide which file is wrong. Use the same requirement to examine two possible situations.

Branch B is an alternative example, not a second test that should be added to Branch A. Its conflicting assertion would be:

# Alternative scenario only: this expectation conflicts with AV-2.
self.assertEqual(remaining_slots(4, 4), 1)

Perhaps someone once wanted to display “at least one place,” or copied the wrong example into a test. That story is not evidence. If the current requirement is still AV-2, the expectation of one is unsupported. If a newer authoritative requirement contradicts AV-2, resolve which requirement applies before changing behavior.

This distinction prevents two opposite mistakes: changing correct code to satisfy a wrong assertion, or weakening a valid assertion to accommodate wrong code.

Use a few boundary cases to define the repair

The candidate correction for Branch A is:

def remaining_slots(capacity, booked):
    return max(capacity - booked, 0)

The following expectations follow from AV-2 by manual reasoning:

These are selected boundaries for the named function. They do not cover every application behavior or introduce requirements for negative values, strings, fractional values, concurrency, or booking authorization.

Keep the original exact-capacity assertion. Add a focused case only when it checks a meaningful part of the rule. For example:

class AvailabilityTests(unittest.TestCase):
    def test_full_capacity_has_no_open_places(self):
        self.assertEqual(remaining_slots(4, 4), 0)

    def test_over_capacity_never_displays_negative_places(self):
        self.assertEqual(remaining_slots(4, 5), 0)

    def test_one_place_left_is_preserved(self):
        self.assertEqual(remaining_slots(4, 3), 1)

    def test_zero_capacity_has_no_open_places(self):
        self.assertEqual(remaining_slots(0, 0), 0)

    def test_no_bookings_leave_capacity_open(self):
        self.assertEqual(remaining_slots(4, 0), 4)

This is an illustrative replacement class for the same test module, using its imports above. Whether these assertions already exist elsewhere must be checked in the actual repository before adding duplicates.

Copy this completed repair request

Repair remaining_slots in availability.py against requirement AV-2.

Requirement AV-2:
Inputs in scope are non-negative integers. Return capacity minus booked
when booked is below capacity; otherwise return zero. The function only
calculates a displayed count and does not authorize bookings.

Current implementation:
def remaining_slots(capacity, booked):
    return max(capacity - booked, 1)

Existing assertion in tests/test_availability.py:
self.assertEqual(remaining_slots(4, 4), 0)

Failure status:
Manual reasoning predicts actual 1 versus expected 0. No terminal run
has been supplied in this example. Inspect the current repository rather
than claiming this is a reproduced failure.

First:
Confirm the current implementation and assertion. Check whether a newer
requirement supersedes AV-2. State whether the implementation or expected
value conflicts with the applicable requirement, with file references.

Allowed edits:
availability.py and tests/test_availability.py only.
Preserve the function name, parameter order, return type for in-scope
inputs, and existing correct expectations. Keep the exact-capacity test.

Required behavior to check:
(4,0)->4; (4,3)->1; (4,4)->0; (4,5)->0; (0,0)->0.
Reuse existing coverage where present. Add focused missing cases without
changing unrelated tests or replacing the test framework.

Out of scope:
Booking writes, database rules, UI redesign, concurrency, dependencies,
new validation/coercion behavior for out-of-contract inputs, and release.

Verification in the authorized development environment:
Use the repository's documented test command. The supplied teaching
layout suggests python -m unittest discover -s tests from the root;
verify that this matches the actual project before running it.

Return:
Small diff; requirement-to-change explanation; exact commands run and
results, or explicit unrun reasons; remaining gaps. Never present manual
evaluation as a test run. If the authoritative requirement is missing or
conflicting, report that conflict before changing expected values.

Separate the reasoning record from the execution record

An agent can explain a likely one-line correction without having reproduced it. That is useful analysis, provided the delivery says which stage was completed. A recorded passing test would add evidence for the selected cases; it would not establish that every booking workflow is correct.

Before accepting the patch, compare its behavior with AV-2, then read the test results and remaining gaps. If a valid requirement assertion disappeared or its expectation changed without a requirement change, the original problem may have been hidden instead of repaired.

For the CueSpec conversation step, read the latest answer before issuing the repair request. Keep the exact assertion and requirement text with the task so that a spoken explanation does not replace the numbers or boundary conditions.