fix(instructions): stop mandating a milestone for every non-trivial task
CI & Build / Python lint (push) Successful in 4s
CI & Build / Plugin hooks (push) Failing after 11s
CI & Build / integration (push) Successful in 19s
CI & Build / TypeScript typecheck (push) Successful in 26s
CI & Build / Python tests (push) Successful in 43s
CI & Build / Build & push image (push) Successful in 28s

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
This commit is contained in:
2026-07-31 20:39:20 -04:00
co-authored by Claude Opus 5
parent 378a4b8f99
commit 6eedb0f6b9
4 changed files with 50 additions and 27 deletions
+7 -5
View File
@@ -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,
title)` FIRST — it creates a milestone whose `body` holds the design; each
step is its own task under that milestone (`create_task(milestone_id=...)`),
progress goes in work-logs (`add_task_log`). Read it back with `get_milestone`.
Do not write plans/specs to local `.md` files.
4. **When you plan, plan in Scribe.** Work with an *arc* — several steps toward
one goal — gets a plan, and a plan is a milestone: `start_planning(project_id,
title)` creates one whose `body` holds the design, each step is its own task
under it (`create_task(milestone_id=...)`), progress goes in work-logs
(`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.
+24 -6
View File
@@ -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** —
before any design or implementation. 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:
A plan lives in a milestone, and **a milestone earns its place when the work has
an arc**: several steps, one shared goal, a beginning and an end worth tracking
as a unit. That is the whole test, and it is a judgment about the *shape* of the
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=...)`.