bvandeusenandClaude Opus 5.5
79de8938b9
Module and test docstrings state what is pinned without the record number or step that introduced it. Incident accounts become the failure shape in the present tense: the pipefail head, the code_shapes import, the export order, the facet dialects, the cross-kind repeat, the write-once kind. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
82 lines
3.5 KiB
Python
82 lines
3.5 KiB
Python
"""Every create_* tool says what it is NOT for.
|
|
|
|
WHY THIS EXISTS
|
|
|
|
Scribe's record kinds are reached for interchangeably — a note written where
|
|
a task was owed, a rule written where a snippet belonged — and the moment of
|
|
choice is the only moment a correction is cheap. The tool docstring IS the
|
|
agent-facing contract (product guidance lives there and nowhere else), so a docstring that only documents parameters answers "how do I call
|
|
this" while leaving "should I be calling this at all" unasked.
|
|
|
|
The gap was lopsided before this: `create_rule` and `start_planning` both
|
|
carried a real disambiguator, and `create_note` — far and away the
|
|
highest-volume surface — carried none. Guidance sat in the rarest tool and
|
|
was missing from the most common one.
|
|
|
|
WHAT THIS PINS, AND WHAT IT DOES NOT
|
|
|
|
It asserts STRUCTURE, never wording: each create surface must name at least
|
|
two sibling surfaces, so a caller who reached for the wrong one is told
|
|
where the right one is. Prose stays free to be rewritten — pinning phrasing
|
|
would make every improvement a test failure, and a test that punishes
|
|
editing is a test that gets deleted.
|
|
|
|
It cannot tell whether the guidance is any GOOD. It only catches the
|
|
regression that actually happens: a docstring rewritten down to its
|
|
parameters, with the "is this even the right tool" paragraph quietly gone.
|
|
"""
|
|
import re
|
|
|
|
import pytest
|
|
from tests.helpers import tool_doc as _doc
|
|
|
|
# The create surfaces and where they live. `start_planning` is here because
|
|
# it is a create in everything but name — it is how a plan comes into being.
|
|
_SURFACES = [
|
|
("scribe.mcp.tools.notes", "create_note"),
|
|
("scribe.mcp.tools.tasks", "create_task"),
|
|
("scribe.mcp.tools.tasks", "create_records"),
|
|
("scribe.mcp.tools.tasks", "start_planning"),
|
|
("scribe.mcp.tools.snippets", "create_snippet"),
|
|
("scribe.mcp.tools.processes", "create_process"),
|
|
("scribe.mcp.tools.rulebooks", "create_rule"),
|
|
("scribe.mcp.tools.rulebooks", "create_project_rule"),
|
|
]
|
|
|
|
# What a caller could have wanted instead. A surface naming two of these has
|
|
# pointed somewhere; naming none has left them where they were.
|
|
_ALTERNATIVES = [
|
|
"create_note", "create_task", "create_rule", "create_project_rule",
|
|
"create_snippet", "create_process", "start_planning", "design system",
|
|
]
|
|
|
|
|
|
@pytest.mark.parametrize(("module", "name"), _SURFACES)
|
|
def test_a_create_surface_names_at_least_two_alternatives(module, name):
|
|
"""Reaching for the wrong tool must still put the right one in view."""
|
|
doc = _doc(module, name)
|
|
named = {
|
|
alt for alt in _ALTERNATIVES
|
|
if alt != name and re.search(re.escape(alt), doc, re.IGNORECASE)
|
|
}
|
|
assert len(named) >= 2, (
|
|
f"{name}'s docstring names {sorted(named) or 'no'} alternative "
|
|
f"surface(s). A caller who reached for it by mistake gets no "
|
|
f"correction. Say what belongs elsewhere and why — see create_rule "
|
|
f"or create_note for the shape."
|
|
)
|
|
|
|
|
|
@pytest.mark.parametrize(("module", "name"), _SURFACES)
|
|
def test_a_create_surface_still_documents_its_arguments(module, name):
|
|
"""The guard above must not be satisfiable by deleting the parameter docs.
|
|
|
|
Both halves matter and they pull in opposite directions: a docstring can
|
|
be made to pass the disambiguator check by becoming an essay about the
|
|
other tools, which would be a worse contract than the one being fixed.
|
|
"""
|
|
assert "Args:" in _doc(module, name), (
|
|
f"{name}'s docstring lost its Args: block — the parameter contract is "
|
|
f"what a caller reads to make the call at all."
|
|
)
|