From 16805ca22c42e427d58509248a00c0c8e2be7a2e Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Thu, 27 Aug 2026 18:18:42 -0400 Subject: [PATCH 1/4] docs(mcp): every create_* tool says what it is NOT for (#3123) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Scribe's record kinds get reached for interchangeably, and the moment of choice is the only moment a correction is cheap. Rule 119 puts product guidance in the instruction surfaces, so the docstring is where this belongs — but a docstring that only documents parameters answers "how do I call this" and leaves "should I be calling this at all" unasked. The gap was lopsided. create_rule and start_planning already carried real disambiguators; create_note — far and away the highest-volume surface — carried none at all. The guidance sat in the rarest tool and was missing from the most common one. Each surface now opens with ONE deciding question in its own terms rather than a pasted block: create_note WHAT ELSE COULD HOLD THIS? note is right when nothing is owed and nothing enforces create_task IS ANYTHING ACTUALLY OWED? nothing owed -> note; an arc -> start_planning create_snippet SHAPE, OR ADVICE? a snippet is code with a LOCATION create_process FOLLOWED, OR READ? applies uninvoked -> rule create_project_rule now points at the entity check too; it had only ever covered rule-vs-rule scope. The guard asserts STRUCTURE, never wording: each surface must name at least two siblings. Pinning phrasing would make every improvement a test failure, and a test that punishes editing is a test that gets deleted. Its second half asserts the Args: block survives — the first check is satisfiable by turning a docstring into an essay about the other tools, which would be a worse contract than the one being fixed. The guard caught two gaps on its first run, one of them its own: "design system" is hard-wrapped across a line break in create_rule, so matching the raw docstring reported it absent. _doc() now flattens whitespace. It also caught start_planning naming only one alternative, which was true and is now fixed. Deliberately NOT built: an intent-router tool. It has a bootstrapping problem — it is itself a tool that must be reached for — and MCP clients already list every tool's description. Recorded in #3123; build it only if wrong-surface reaches survive this. Co-Authored-By: Claude Opus 5 (1M context) --- src/scribe/mcp/tools/notes.py | 11 +++ src/scribe/mcp/tools/processes.py | 6 ++ src/scribe/mcp/tools/rulebooks.py | 7 ++ src/scribe/mcp/tools/snippets.py | 7 ++ src/scribe/mcp/tools/tasks.py | 11 ++- tests/test_create_tools_disambiguate.py | 95 +++++++++++++++++++++++++ 6 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 tests/test_create_tools_disambiguate.py diff --git a/src/scribe/mcp/tools/notes.py b/src/scribe/mcp/tools/notes.py index 223ac18..d8b3931 100644 --- a/src/scribe/mcp/tools/notes.py +++ b/src/scribe/mcp/tools/notes.py @@ -107,6 +107,17 @@ async def create_note( ) -> dict: """Create a new note in Scribe. + WHAT ELSE COULD HOLD THIS? A note is the right home when the answer is + "nothing": it records what you know, nobody owes anything on it, and + nothing enforces it. Otherwise — + - someone has to DO something -> create_task. A note titled "we should…" + is a task nobody will ever see again. + - future sessions must OBEY it -> create_rule. The test is whether + ignoring it would be a mistake, not merely uninformed. + - reusable code with a place in a repo -> create_snippet. The location is + what lets it be found from the file someone is about to edit. + - a procedure followed start to finish -> create_process. + Args: title: Note title (required). body: Markdown content. Supports [[wikilinks]] to other notes by title. diff --git a/src/scribe/mcp/tools/processes.py b/src/scribe/mcp/tools/processes.py index e3994b6..df755be 100644 --- a/src/scribe/mcp/tools/processes.py +++ b/src/scribe/mcp/tools/processes.py @@ -54,6 +54,12 @@ async def create_process( ) -> dict: """Create a stored process (a reusable saved prompt). + FOLLOWED, OR READ? A process is invoked deliberately and worked through + start to finish. If it should apply whether or not anyone invokes it, it + is a rule (create_rule) — that is the whole difference between a procedure + and a standing instruction. If it is knowledge to consult rather than + steps to execute, it is a note (create_note). + AUTHOR IT AS A SHAPE, NOT A SCRIPT. A process's value is the accumulated procedure — the steps, the taxonomy, the quality bar, the failure modes worth guarding. It must not force anything the invoking conversation diff --git a/src/scribe/mcp/tools/rulebooks.py b/src/scribe/mcp/tools/rulebooks.py index ee5da8e..a5c2dde 100644 --- a/src/scribe/mcp/tools/rulebooks.py +++ b/src/scribe/mcp/tools/rulebooks.py @@ -407,6 +407,13 @@ async def create_project_rule( the rule is returned in get_project's applicable_rules (under project_rules) and in list_rules(project_id=...). + Check first whether a rule is the right shape at all — create_rule's + opening asks that question and it applies identically here. A visual + standard is a design system; a procedure is a process (create_process); + reusable code is a snippet (create_snippet). Each of those is structure a + tool can resolve, render and check, where a rule is only prose someone + has to remember and apply. + ONE RULE = ONE THING YOU COULD VIOLATE — see create_rule. A rule that STRICTENS or REPLACES an inherited one is not a fresh rule: write it, then relate_rules(kind="overrides") to the rule it supersedes, so the pair stays diff --git a/src/scribe/mcp/tools/snippets.py b/src/scribe/mcp/tools/snippets.py index ef61aec..faf7d5b 100644 --- a/src/scribe/mcp/tools/snippets.py +++ b/src/scribe/mcp/tools/snippets.py @@ -115,6 +115,13 @@ async def create_snippet( """Record a shape in the project's pattern library, so every later instance starts from it instead of re-deriving it. + IS THE SHAPE THE POINT, OR THE ADVICE? A snippet is code with a LOCATION — + that is what lets it surface from the file someone is about to edit. If + what wants recording is a standing instruction about how to work, it is a + rule (create_rule); a procedure followed start to finish is a process + (create_process); what you LEARNED rather than what to copy is a note + (create_note). + Reach for this the FIRST time any shape is built — a component, a control, a route handler, a service class, a helper, a test scaffold — not only when something is judged "reusable": the builder of the first instance diff --git a/src/scribe/mcp/tools/tasks.py b/src/scribe/mcp/tools/tasks.py index c0221e1..3a17aef 100644 --- a/src/scribe/mcp/tools/tasks.py +++ b/src/scribe/mcp/tools/tasks.py @@ -135,6 +135,13 @@ async def create_task( ) -> dict: """Create a new task in Scribe. + IS ANYTHING ACTUALLY OWED? A task carries a status and someone is on the + hook to move it. If nothing is owed — you are recording what you learned, + decided or observed — that is a note (create_note), and filing it here + leaves a to-do nobody will ever close. If the work is an ARC of several + steps toward one goal, start_planning makes the milestone that holds + them; a task is one step, not the plan. + Args: title: Task title (required). body: Markdown description / notes for the task. @@ -323,7 +330,9 @@ async def start_planning(project_id: int, title: str) -> dict: Reach for this when the work has an ARC — several steps toward one goal, worth tracking as a unit. Work without one (a fix, a one-file change, a question answered) is a task, not a plan: create_task, drive its status, and - record progress with add_task_log. A milestone holding a single step is + record progress with add_task_log. A design or decision you are RECORDING + rather than executing is a note (create_note) — a plan nobody is going to + work through is a document filed in the place reserved for open work. A milestone holding a single step is ceremony, and it leaves the project with a plan that never meant anything. Creates a MILESTONE that IS the plan: its `body` is seeded with a design diff --git a/tests/test_create_tools_disambiguate.py b/tests/test_create_tools_disambiguate.py new file mode 100644 index 0000000..360009c --- /dev/null +++ b/tests/test_create_tools_disambiguate.py @@ -0,0 +1,95 @@ +"""Every create_* tool says what it is NOT for (#3123). + +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 (rule 119 puts product guidance 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 + +# 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", "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", +] + + +def _doc(module: str, name: str) -> str: + """The docstring with its whitespace flattened. + + Flattened because a docstring is hard-wrapped: "design system" spans a + line break in at least one of these, and matching the raw text would + report it absent. The first draft of this check did exactly that, and + caught it on itself. + """ + import importlib + + fn = getattr(importlib.import_module(module), name) + assert fn.__doc__, f"{name} has no docstring at all" + return re.sub(r"\s+", " ", fn.__doc__) + + +@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." + ) From a0b54ff6a327783d64f98be563d58177cb8f48d0 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Thu, 27 Aug 2026 18:43:45 -0400 Subject: [PATCH 2/4] =?UTF-8?q?feat(ui):=20task=20rows=20show=20their=20ki?= =?UTF-8?q?nd=20=E2=80=94=20a=20badge=20for=20issue=20and=20spike=20(#3124?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit task_kind was only visible inside the task editor's Kind select, so every list surface rendered work, issue and spike identically and a list of tasks hid the fact that three different things were in it. ONE component, not a fifth spelling. The badge layer had already drifted — StatusBadge.vue is the recorded canon (#2960) but WorkspaceTaskPanel, ProjectView and KnowledgeView each carry their own scoped `.status-badge`. KindBadge is modelled on PriorityBadge, its closest sibling, which already does the thing that matters here: the DEFAULT value renders nothing. `work` is most tasks, so badging it would put a chip on nearly every row and say nothing — the same reason RuleListPane marks only `conditional`. COLOUR BY TEMPERATURE, measured rather than eyeballed. Issue and spike are opposite in character — corrective vs exploratory — so they split warm (warning) against cool (info), which survives being small and stays distinguishable without reading the word. Neither uses the accent; kind is not one of the places it is allowed. The raw semantic colour FAILS the contrast floor on the dark palette: warning on its own 12% tint measures 2.97:1 against AA's 4.5. So the text is the hue mixed toward --fs-text-primary, which passes and, because that token inverts by mode, follows light/dark for free. Measured both ways — issue 5.23:1 dark / 6.68:1 light, spike 5.33:1 / 9.26:1. `plan` renders hue-free and italic: retired since 0066, so a legacy row should read as archival rather than as a fourth kind competing for attention. In KnowledgeView it is passed as null instead, because the type badge beside it already says "Plan" and two chips reading the same word would look like two facts. Weight is 500, not the 600 the two older badges use — the house style allows 400 and 500 only, and copying 600 would spread it. SERVER FIX, without which this was decorative: dashboard's `_task_row` omitted task_kind entirely. The badge would have rendered nothing there while working everywhere else, which reads as "this list has no issues" rather than as a missing field. The guard is on the payload, where the omission was. Surfaces: ProjectView's three status columns, WorkspaceTaskPanel's two task lists, DashboardView's milestone and no-milestone rows, KnowledgeView's result rows. Co-Authored-By: Claude Opus 5 (1M context) --- frontend/src/components/KindBadge.vue | 79 +++++++++++++++++++ .../src/components/WorkspaceTaskPanel.vue | 5 ++ frontend/src/views/DashboardView.vue | 6 +- frontend/src/views/KnowledgeView.vue | 10 ++- frontend/src/views/ProjectView.vue | 6 ++ src/scribe/services/dashboard.py | 7 +- tests/test_services_dashboard.py | 25 +++++- 7 files changed, 134 insertions(+), 4 deletions(-) create mode 100644 frontend/src/components/KindBadge.vue diff --git a/frontend/src/components/KindBadge.vue b/frontend/src/components/KindBadge.vue new file mode 100644 index 0000000..3622a96 --- /dev/null +++ b/frontend/src/components/KindBadge.vue @@ -0,0 +1,79 @@ + + + + + diff --git a/frontend/src/components/WorkspaceTaskPanel.vue b/frontend/src/components/WorkspaceTaskPanel.vue index 09ad42e..982a5cc 100644 --- a/frontend/src/components/WorkspaceTaskPanel.vue +++ b/frontend/src/components/WorkspaceTaskPanel.vue @@ -4,6 +4,8 @@ import { RouterLink } from "vue-router"; import { apiGet, apiPatch, apiPost, apiDelete } from "@/api/client"; import { useToastStore } from "@/stores/toast"; import TaskLogSection from "@/components/TaskLogSection.vue"; +import KindBadge from "@/components/KindBadge.vue"; +import type { TaskKind } from "@/types/note"; import { renderMarkdown } from "@/utils/markdown"; import { Trash2, X } from "lucide-vue-next"; import { relativeTimeOrDate } from "@/composables/useRelativeTime"; @@ -28,6 +30,7 @@ interface Task { due_date: string | null; updated_at: string; body?: string; + task_kind?: TaskKind; } const tasks = ref([]); @@ -242,6 +245,7 @@ defineExpose({ reload: loadAll }); {{ task.title }} + {{ task.due_date }} {{ relativeTimeOrDate(task.updated_at) }} @@ -267,6 +271,7 @@ defineExpose({ reload: loadAll }); {{ task.title }} + {{ task.due_date }} {{ relativeTimeOrDate(task.updated_at) }} diff --git a/frontend/src/views/DashboardView.vue b/frontend/src/views/DashboardView.vue index 5ee73e8..da19833 100644 --- a/frontend/src/views/DashboardView.vue +++ b/frontend/src/views/DashboardView.vue @@ -1,9 +1,11 @@ + + + + diff --git a/frontend/src/components/StatusBadge.vue b/frontend/src/components/StatusBadge.vue index f818178..5037f3b 100644 --- a/frontend/src/components/StatusBadge.vue +++ b/frontend/src/components/StatusBadge.vue @@ -4,13 +4,16 @@ import type { TaskStatus } from "@/types/task"; const props = defineProps<{ status: TaskStatus; clickable?: boolean; + /** Dense surfaces — smaller, unshouted. The canon (#2960) names compact a + VARIANT of this component rather than a reason to re-spell it. */ + compact?: boolean; }>(); defineEmits<{ click: [] }>(); const labels: Record = { todo: "Todo", - in_progress: "In Progress", + in_progress: "In progress", done: "Done", cancelled: "Cancelled", }; @@ -18,7 +21,7 @@ const labels: Record = {