spec-flow-plugin CLAUDE.md

Working agreements for this repo

This engine exists to close one failure: a check that looks armed and is not. The same standard applies to work done on it.

Verify before you claim, and before you propose

A claim without a run behind it is not a finding. Reading the code is how you form a hypothesis; running it is how you learn whether the hypothesis is true. Every defect worth reporting here was found by executing something — several of them contradicted what the source appeared to say.

Before proposing that something be REMOVED, verify what it uniquely provides — not merely that an alternative exists. This is its own rule because it has its own failure mode: finding one good argument for deletion feels like finishing the investigation, and it is the point at which the investigation has barely started. An alternative covering part of a job is evidence about that part and says nothing about the rest.

The concrete case is worth the whole story, because it ends somewhere surprising.

.spec-flow/skills.md was proposed for deletion because Claude Code already lists every skill's name and description to the model, so the table was "redundant for discovery". That was true and irrelevant: discovery was one of three jobs the table did. Two doc quotes supported removal; nothing was checked that could have contradicted them. The proposal was withdrawn.

And the file was deleted anyway, two days later, for reasons the first proposal never touched. Nothing read it — no script parsed it, and the one check that mentioned it only tested that the file existed — so it could name skills that had been renamed or deleted and nobody would learn. Its three jobs each turned out to have an owner elsewhere: a skill's own description maps the decision, the project's agent frontmatter records what it preloads, and the milestone's Skills: field is the instruction. None of that was known when removal was first proposed.

So the lesson is not "do not remove things". It is that being right about the conclusion is not the same as having verified it, and the first version of this argument would have been indistinguishable from the second to anyone reading only the outcome. What separated them was whether anyone had gone looking for the half that disagreed.