bvandeusenandClaude Opus 5
441a1ac31d
Sessions predicted the ids their next creates would get and wrote them into
plan bodies and reference notes before the records existed. The database
never collides; the sequence is shared by every session and user, so any
concurrent create took the guessed numbers and the references pointed at
someone else's records.
- create_records (new MCP tool) and start_planning(body=, steps=) create
their records in ONE transaction: insert, flush for the real ids, rewrite
{{ref:N}} / {{ref:milestone}} placeholders as #id "title", commit. No
prediction, no waiting, no stub records left behind when a batch fails.
Ids need not be consecutive and nothing depends on it.
- Every MCP create/update of a note, task or milestone refuses a #N sitting
just above the highest assigned id (within 50): that can only be a guess.
Refusal, not warning. Numbers far above the max (PRs, forge issues) pass.
- notes.build_note splits validation out of create_note so the batch
validates records exactly as a single create does.
- writing-plans and using-scribe say to pass steps up front and never write
an unassigned id; plugin version minted.
Integration test runs six concurrent batches and checks each resolves its
placeholders to its own records, and that a failing batch writes nothing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
4.7 KiB
name, description
| name | description |
|---|---|
| writing-plans | 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
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.
First decide whether this work wants a plan
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— pass it asstart_planning(..., body=...), or edit it later withupdate_milestone(milestone_id, body=...). - Each step is its own task under the milestone. When you know the steps,
pass them in the same call —
start_planning(..., steps=[{title, body}, …])— and the milestone and every step are created together. Add steps later withcreate_records(milestone_id=<that milestone>, records=[…]), orcreate_taskfor one. Track each with status +add_task_log. Steps are first-class tasks, not checkboxes in the body. - Read the whole plan back with
get_milestone(body + its step-tasks).
Never write an id you have not been given. A plan body that says "see
#4012" before #4012 exists is a guess, and other sessions and users are
creating records from the same sequence at the same time — the number goes to
whoever creates next, and the plan then points at their record. Scribe refuses
a body citing an id that has not been assigned. Where the plan and its steps
need to cite each other, write a placeholder instead: {{ref:N}} is the Nth
step in the list, {{ref:milestone}} is the milestone. They are replaced with
the real id and title as the records are created.
Do not write plans or specs to local .md files — the milestone is the
record, not a file on disk. (The old kind=plan task is retired; start_planning
no longer creates one.)
Before designing from scratch, recall: search Scribe for a related prior
plan or decision. Often the thinking (or half of it) already exists.
What a good plan contains
- Goal — what "done" looks like, and why, in a sentence or two (milestone body).
- Approach — the key design decisions and the trade-offs you chose, briefly (milestone body).
- Steps — an ordered set of step-tasks under the milestone, each small enough to verify on its own; note which files/areas each touches.
- Verification — how you'll know it actually works (a test, CI, an observable behavior), not just "it's written."
While executing
- Keep the plan honest: drive each step-task's status (todo →
in_progress → done) as it lands; record decisions, findings, and pivots with
add_task_logon the relevant step rather than silently rewriting the body. - If reality diverges from the plan, update the milestone body — a design that no longer matches what you're doing is worse than none. Add or re-scope step-tasks as the work changes.
- Mark the milestone
donewhen its steps are complete.
Match depth to the work
A two-step change deserves a two-line plan; a multi-day effort deserves a fleshed-out milestone body and several step-tasks. Don't over-plan the trivial, and don't under-plan something that will sprawl. The point is a shared, reviewable intent — not ceremony.