bvandeusenandClaude Opus 5.5
17777e9bb1
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 15s
CI & Build / TypeScript typecheck (push) Successful in 53s
CI & Build / integration (push) Successful in 1m10s
CI & Build / Python tests (push) Successful in 1m55s
CI & Build / Build & push image (push) Successful in 39s
MCP tool docstrings and comments, the server's orientation notes, the plugin skills, every hook script and the plugin README/PACKAGING drop record ids, milestone numbers, dates and incident stories, and state each non-obvious why as a present-tense fact. History stays in the task logs. Corrections found on the way: - plugin README/PACKAGING said every hook is a GET; moment, rule-opened and reply-rules POST, so the plugin's key needs write scope. Both now say so, name Settings -> MCP Access, and list every wired hook and endpoint. - the contract-change hint printed "(lesson #4207)", this instance's record, to every install. It no longer cites a record. - tasks.py claimed there is no delete_task; there is. - rulebooks.py cited delete_event and a design spec that no longer exist. - scribe_after_write.sh carried an always-empty etag_q; removed. - test_write_path_trigger pinned "| tac | scribe_defs | head -1", text that existed only in a comment about the old code; it now pins the real tail -1 pipeline. - docs/development.md: CI runs on Gitea Actions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
120 lines
6.3 KiB
Markdown
120 lines
6.3 KiB
Markdown
---
|
|
name: writing-plans
|
|
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.
|
|
metadata:
|
|
moments: work.plan
|
|
---
|
|
|
|
# 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.
|
|
|
|
## Then look for the plan that already exists
|
|
|
|
Before you start a plan, find out whether the project already has one for this
|
|
work. A roadmap is often written ahead of the work as milestones with a goal
|
|
and no steps yet, and those are exactly the plans a session misses: they have
|
|
nothing in them to show up as open tasks.
|
|
|
|
- `enter_project` lists the recent milestones and, under `unplanned_milestones`,
|
|
the active ones with no steps.
|
|
- `search(content_type="milestone", project_id=...)` finds a plan by what it is
|
|
for. `list_milestones` reads the whole roadmap.
|
|
|
|
**When an active milestone already covers the work, the plan is that milestone.**
|
|
Read it with `get_milestone`, add your steps with
|
|
`create_records(milestone_id=<its id>, records=[…])`, and revise its body with
|
|
`update_milestone` if what you know now changes the design. Opening a new
|
|
milestone beside it splits one piece of work across two plans, and neither
|
|
shows the whole. A second milestone is right only when the work is a separate
|
|
arc: a different goal that would still make sense if the first plan were done.
|
|
|
|
The same holds for single tasks. Work that belongs to an existing plan is
|
|
created with that milestone's `milestone_id`, not left loose beside it.
|
|
|
|
`start_planning` and `create_milestone` check too. When an active milestone in
|
|
the project has the same title or reads as the same plan, they return it as
|
|
`existing_milestone` and create nothing. Add to that plan, or pass `force=true`
|
|
only when you have read it and this really is separate work.
|
|
|
|
## 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 as
|
|
`start_planning(..., body=...)`, or edit it later with
|
|
`update_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
|
|
with `create_records(milestone_id=<that milestone>, records=[…])`, or
|
|
`create_task` for 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. A plan is never a task: `kind="plan"` is refused,
|
|
and `start_planning` makes a milestone.
|
|
|
|
Before designing from scratch, **recall**: `search` Scribe for a related prior
|
|
decision or note. 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_log` on 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 `done` when 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.
|