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
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:
@@ -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.
|
||||
|
||||
@@ -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=...)`.
|
||||
|
||||
Reference in New Issue
Block a user