Alberto-Codes / Alberto-Codes/vramfit

PassOutcome.sample_phrase's docstring promises a guarantee the code does not keep on an all-excluded pass

Open Beginner friendly
#596 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1
Forks
1
Avg merge
5h 57m
Merged PRs (30d)
110

Description

## Problem

`PassOutcome.sample_phrase` promises a guarantee it does not keep.

The docstring states it returns:

> the arms measured and the neighbourhood they came from, naming the
> judged count separately **whenever the budget excluded any**

The code names the judged count only when **both** sets are non-empty:

```python
phrase = f"{self.measured()} evaluated"
if self.measured() != self.neighbourhood_moves:
phrase = f"{phrase} of a neighbourhood of {self.neighbourhood_moves}"
if self.excluded and self.judged:
return f"{len(self.judged)} judged of {phrase}"
return phrase
```

So when the budget excludes **every** arm, `self.judged` is empty, the
branch does not fire, and the judged count is not named. The budget
excluded some, and the guarantee did not hold.

## What is and is not reachable

The **code path is reachable today and is tested** —
`test_an_all_excluded_pass_reports_none_judged_rather_than_none_measured`
exercises exactly the all-excluded case.

What is not reachable today is a **wrong sentence**. `summary()`'s
all-excluded branch does not rely on the missing clause:

```
no arm of the N evaluated of a neighbourhood of M was judged on
merit: all N packed over the weight budget
```

That is true and complete, so no operator-facing output is wrong and
no reader of any current surface is misled.

**The trigger.** It becomes a live misstatement the moment a third
surface calls `sample_phrase()` directly and trusts the docstring's
guarantee, instead of reaching it through `summary()`. That surface
would print a sample phrase that silently omits the judged count on an
all-excluded pass.

## The fix is to the docstring, not the code

**Do not make the sentence say "0 judged".** The code is correct: on a
pass where the budget excluded everything, "0 judged of 15 evaluated"
is the odd phrasing, and `summary()` already says the true thing in
better words.

Correct the docstring to describe what the function does — the judged
count is named separately when the budget excluded **some but not
all** arms.

## The class this belongs to

A docstring promising a guarantee the function does not keep is the
same defect family the refinement-stage change spent its review
closing: **a record stating something untrue**. ADR-0031's
consequences record that this class and the re-derivation class were
both cured by changing the shape so the wrong version has nowhere to
live, never by stating the rule more clearly.

It is also the exact shape that produced the duplicated exclusion
classifier that change removed — one surface trusting a description
rather than the structure. Making the docstring describe the code is
the structural direction. Adding code to satisfy the docstring is the
wrong one.

## Provenance

Found by the review pass on the change that introduced `PassOutcome`
(PR #595), named in that run's risk line as "an unreachable-today
misstatement in the new shared classifier", and shipped as a known
limitation rather than paying a full re-validation of 27 files for one
docstring line. It is recorded in the PR body as well as here.

Contributor guide

Open the contributing guide

Research direction

Start at PassOutcome.sample_phrase and read its docstring alongside the existing test test_an_all_excluded_pass_reports_none_judged_rather_than_none_measured. Update the docstring so it says the judged count is named when the budget excluded some but not all arms; leave the code unchanged and confirm the existing all-excluded test still passes.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.