fix(instructions): stop mandating a milestone for every non-trivial task

Four product surfaces told the agent to call start_planning FIRST for any
"non-trivial" work, while a fifth — the milestone bullet four lines up in the
same file — had the criterion right: use one when the work has an arc. The
loudest surface won, so sessions wrapped bug fixes and one-file changes in
milestones that never meant anything.

Mandating one project shape is what rule #115 forbids: some projects are
milestone-shaped, others are a flat task list and always will be.

Now the arc test is stated ONCE in full, in writing-plans, along with what to
do when there is no arc (a task, driven by status and work-logs). The other
surfaces name it and defer:

- writing-plans/SKILL.md gains a "first decide whether this work wants a plan"
  section; its frontmatter trigger is the arc, not "non-trivial"
- using-scribe reflex #4 points at the skill instead of restating it
- server.py's Plan bullet adopts the milestone bullet's own criterion
- server.py's planning paragraph drops from 11 lines to 6: it keeps the claim
  MCP instructions should make (a plan's HOME is a milestone, not a local .md)
  and drops the how, which the skill carries
- start_planning's docstring gains the when

Also removed "call start_planning FIRST — before any brainstorming, design, or
plan-writing skill runs." That was the server asserting priority over the skill
layer. Tools describe what they do; skills decide when they apply.

The structural point outlasts the wording: a surface that restates a rule is a
surface that will eventually contradict it, and nothing checks prose against
prose.

Closes #2322.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UaYUaouG9jjhATyuxCKrQs

plugin/skills/using-scribe/SKILL.md

@@ -64,11 +64,13 @@ Two constraints on *how* that's achieved:
 3. **Update over duplicate.** When recording, prefer updating an existing
    note/rule/task over creating a new one. Search first; revise what's there.
 
-4. **Plans live in Scribe.** For non-trivial work call `start_planning(project_id,
+4. **When you plan, plan in Scribe.** Work with an *arc* — several steps toward
-   title)` FIRST — it creates a milestone whose `body` holds the design; each
+   one goal — gets a plan, and a plan is a milestone: `start_planning(project_id,
-   step is its own task under that milestone (`create_task(milestone_id=...)`),
+   title)` creates one whose `body` holds the design, each step is its own task
-   progress goes in work-logs (`add_task_log`). Read it back with `get_milestone`.
+   under it (`create_task(milestone_id=...)`), progress goes in work-logs
-   Do not write plans/specs to local `.md` files.
+   (`add_task_log`). Work without an arc (a fix, a one-file change, a question)
+   is just a task — don't wrap it in a milestone. Either way, do not write
+   plans/specs to local `.md` files. See the **writing-plans** skill.
 
 5. **Keep state honest.** Set a task `in_progress` when you start it, `done` the
    moment it's complete; log progress as you go.

plugin/skills/writing-plans/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-plans
-description: Use before starting any non-trivial or multi-step piece of work — produce a clear plan BEFORE diving in. Triggers when the user asks you to plan, design an approach, scope an effort, or tackle work big enough to need ordered steps. The plan lives in a Scribe milestone (via start_planning), not a local file.
+description: Use when a piece of work has an arc — several steps toward one goal, worth tracking as a unit — and you want the approach reviewable before you start. Triggers when the user asks you to plan, design an approach, or scope an effort, or when work is about to sprawl across several steps. Not for single-step work. The plan lives in a Scribe milestone (via start_planning), not a local file.
 ---
 
 # Writing plans
@@ -9,12 +9,30 @@ A plan is **how** you'll execute a chunk of work — the design plus an ordered
 set of steps — written *before* you start, so the approach is reviewable and the
 work stays trackable.
 
-## Start the plan in Scribe, not a file
+## First decide whether this work wants a plan
 
-For non-trivial work, call **`start_planning(project_id, title)` FIRST** —
+A plan lives in a milestone, and **a milestone earns its place when the work has
-before any design or implementation. It creates a **milestone** (the plan
+an arc**: several steps, one shared goal, a beginning and an end worth tracking
-container) seeded with a design template and returns the milestone id plus the
+as a unit. That is the whole test, and it is a judgment about the *shape* of the
-project's applicable rules. The plan lives in that milestone:
+work — not about its size, difficulty, or importance.
+
+Plenty of real work has no arc. A bug fix, a one-file change, a question
+answered, a setting changed. For those, a milestone is a container with one
+thing in it: the ceremony costs more than it records, and it leaves the project
+with milestones that never meant anything. **Use a task instead** — set it
+`in_progress`, record what you find with `add_task_log`, set it `done`. That is
+a complete, honest record of work that didn't need a plan.
+
+Some projects are milestone-shaped and some are a flat task list. Read the
+project you are in rather than imposing a shape on it.
+
+## When it does: start the plan in Scribe, not a file
+
+Call **`start_planning(project_id, title)`** before designing or implementing —
+so the milestone exists to write into, rather than being backfilled from work
+already done. It creates a **milestone** (the plan container) seeded with a
+design template and returns the milestone id plus the project's applicable
+rules. The plan lives in that milestone:
 
 - The **design/intent** goes in the milestone `body` — edit it with
   `update_milestone(milestone_id, body=...)`.

src/scribe/mcp/server.py

@@ -33,11 +33,12 @@ What each part is for, and when to reach for it:
 - Plan: a MILESTONE acting as a plan container — HOW you'll execute a chunk of
   work. The design/intent lives in the milestone `body`; each step is its own
   child task (create_task(milestone_id=...)), tracked with status + work-logs —
-  NOT a checkbox buried in the body. Start one with start_planning when
+  NOT a checkbox buried in the body. Create one with start_planning when the
-  beginning non-trivial work, before you dive in; read it back with
+  work has an arc (same test as a milestone, above) and you want the approach
-  get_milestone (body + steps). (The old kind=plan task is retired — some
+  reviewable before you start; read it back with get_milestone (body + steps).
-  historical plan-tasks still exist and remain readable, but don't create new
+  Work without an arc is a task, not a plan. (The old kind=plan task is retired
-  ones.)
+  — some historical plan-tasks still exist and remain readable, but don't
+  create new ones.)
 - Note: durable free-form knowledge — reference material, decisions, logs of
   what happened.
   No lifecycle, not actionable. Reach for one to CAPTURE something worth keeping.
@@ -184,17 +185,13 @@ adopting or creating — never do either silently, and never guess a project int
 existence. Once a project is in scope, the enter_project handshake and the
 host-memory pointer step above both apply.
 
-A plan is a MILESTONE, and Scribe is the canonical home for it. When you begin
+When work DOES get a plan, Scribe is the plan's canonical home: it is a
-non-trivial work, call start_planning(project_id, title) FIRST — before any
+milestone (see the Plan entry above), created with start_planning and written
-brainstorming, design, or plan-writing skill runs. start_planning creates the
+into with update_milestone + child tasks. If a habit tells you to save a plan or
-milestone, seeds its `body` with the design template, returns the project's
+spec to a local `.md` file, that's superseded here — the milestone is the
-applicable_rules, and gives you the milestone id you'll write into. Put the
+record, not a file on disk. Whether a given piece of work wants a plan at all is
-design/intent in the milestone body via update_milestone(milestone_id, body=...);
+a separate question, answered by the arc test above and by the writing-plans
-create each step as a child task with create_task(milestone_id=...) and track it
+skill; these instructions do not mandate one.
-with status + add_task_log — do NOT list steps as checkboxes in the body. Read
-the plan back with get_milestone (body + steps). If a habit tells you to save a
-plan or spec to a local `.md` file, that's superseded here: the milestone is the
-record, not a local file.
 
 Deletes are recoverable: every delete_* tool moves the entity (and its
 descendants) to the trash and returns a deleted_batch_id. Use list_trash() to

src/scribe/mcp/tools/tasks.py

@@ -276,6 +276,12 @@ async def add_task_log(task_id: int, content: str) -> dict:
 async def start_planning(project_id: int, title: str) -> dict:
     """Begin a plan in Scribe (the preferred home for plans — not a local .md file).
 
+    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
+    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
     template (Goal/Approach/Verification) under the given project, and the call
     returns it together with the project's applicable Rulebook rules and brief