refactor(mcp): _INSTRUCTIONS orients the workflow, not a rulebook (#4389)
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Failing after 12s
CI & Build / TypeScript typecheck (push) Successful in 53s
CI & Build / integration (push) Successful in 54s
CI & Build / Python tests (push) Successful in 1m35s
CI & Build / Build & push image (push) Successful in 23s

Spike #4389 read the spec, Claude's docs and a dozen servers: the field is
for how the tools fit together, and the field runs ~600-1,600 characters.
Ours sat at the 2,048 cap as a keyword index that also carried stance.

- JUDGE, REPORT and MISSED leave the index. They fire mid-work, not at
  session start; using-scribe and reporting-back state them in full, and
  `placement`/`report_back` cue reporting in-band. No skill text changes.
- The rest is rewritten as plain practices (1,503 chars) and keeps every
  session-start marker the ownership registry pins.
- INSTRUCTIONS_BUDGET 2000 -> 1600; the three index markers are dropped
  from the registry; the miss-route index test now checks that the index
  keeps what_might_apply and stays off the route.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-24 07:50:34 -04:00
co-authored by Claude Opus 5.5
parent c26b7f248e
commit 4fb53b844d
5 changed files with 60 additions and 57 deletions
+31 -32
View File
@@ -23,49 +23,48 @@ from quart import Quart
# client's own conventions, never a copy of the above.
# tests/test_guidance_ownership.py holds the topic registry that enforces it.
#
# THIS BLOCK IS THE SERVER'S ORIENTATION, WRITTEN AS AN INDEX. It reaches
# every MCP client, so it names no client, and it points at where each reflex
# is stated rather than restating it. A new topic gets a line here only if it
# is a session-start reflex; its full statement goes to its owner.
# THIS BLOCK IS THE SERVER'S ORIENTATION: the workflow across tools. It reaches
# every MCP client, so it names no client, and it points at where each practice
# is stated rather than restating it. What belongs here, per the spec and the
# field (spike #4389): how the tools fit together — which to call first, which
# before which. What does not: a tool's own contract (its description carries
# it), and stance — who judges, how to report, what a missed rule means. Those
# fire mid-work, not at the start; the skills state them and in-band responses
# (`placement`, `report_back`) cue them at the moment they apply. A new topic
# gets a line here only if it is a session-start practice.
#
# BUDGET: at most 2,000 characters (test_instructions_fit_the_fold). Claude
# BUDGET: at most 1,600 characters (test_instructions_fit_the_fold). Claude
# Code injects only the first ~2,048 characters of a server's instructions and
# cuts the rest mid-word (#2562, observed live), and other clients differ, so
# nothing load-bearing may sit past the fold. The history of what was traded
# nothing load-bearing may sit past the fold; the rest of the field runs
# ~600–1,600 (#4389), and a block pressed against the cap is being used as a
# rulebook. The history of what was traded
# for space before the ownership split (milestones 317, 333, 409) is in
# decision #4027 and the notes it supersedes.
_INSTRUCTIONS = """
Scribe is the operator's system of record, and yours: recall before acting,
record as you go, keep one copy here rather than in local memory files.
record as you go, keep one copy here rather than in local memory files. Each
practice below is stated in full in the using-scribe skill (if your client
reads Agent Skills) and in each tool's description.
Each reflex is stated in full in the using-scribe skill (if your client reads
Agent Skills) and each tool's description. The index:
- ORIENT: enter_project(id) loads the project, open work, Systems and design
- Start with enter_project(id): the project, open work, Systems and design
system. An `inception` key: ask what it inherits, then
decide_project_inception.
- RULES: nothing preloads; a rule arrives when your work matches it. Before a
consequential act, what_might_apply("what you are about to do") — fifty
ranked, no bar. search(content_type="rule") reads one you suspect. Silence
means nothing matched, not none. Rules bind; preferences guide and you keep
them current; lessons inform.
- MISSED: a rule that missed you is a trigger to fix, not a floor to move
(retrieval_telemetry).
- JUDGE: you are the judge of record — what a shape is, whether a finding
holds, whether work is done. Surfacing one for them to rule on is the
judgment not made. Escalate their acts, not your decisions.
- RECALL: search before acting, scoped with the active project_id.
- RECORD: create_task; a fix is kind="issue". add_task_log as you go; status
in_progress on start, done on finish. Tag system_ids.
- PLAN with an arc: find the existing plan first
(search(content_type="milestone")) and add steps to it; else
start_planning(steps=[...]).
- IDS exist only once a create returns them. Records citing each other go
through create_records, writing {{ref:N}} for the Nth record.
- REUSE: search snippets before building; create_snippet what you build.
- UI: the project's design system binds; resolve_design_system before
- Rules are not preloaded; one arrives when your work matches it. Before a
consequential act, what_might_apply("what you are about to do");
search(content_type="rule") reads one you suspect. Silence means nothing
matched, not none. Rules bind; preferences guide and you keep them current;
lessons inform.
- Search before acting or building, scoped with the active project_id; start
from a recorded snippet, and create_snippet what you build.
- Work is tasks (a fix is kind="issue"): in_progress on start, add_task_log as
you go, done on finish; tag system_ids.
- A plan is a milestone: find the existing one
(search(content_type="milestone")) before start_planning.
- IDs exist only once a create returns them; records citing each other go
through create_records, writing {{ref:N}} for the Nth.
- In UI work the project's design system binds: resolve_design_system before
hand-writing a value.
- REPORT from the `placement` a task write returns: where it sits, what
changed, what needs them, what next.
Creates are duplicate-gated: a near-match returns the existing id to update.
shared:true records are another user's suggestion, not settled practice.