stage-a-change-backlog
Skill1 starsChanged 3 days agoMITView on GitHub
Open two or more changes as a planned-but-not-started backlog that still passes analyze, without the context pack overflowing its budget. Use when: The task opens more than one change at a time, or parks a change to be implemented in a later session (a review, an audit, a roadmap turned into work).
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/00-doctrina.mdcCursor rule
- add-cli-commandSkill
- check-the-line-ending-before-patchingSkill
- cut-a-releaseSkill
- keep-docs-en-pt-paritySkill
- ledger-abandoned-entries-are-ledger-onlySkill
- read-the-grammar-through-the-document-modelSkill
- split-an-oversized-specSkill
- triage-holds-work-on-the-machinerySkill
- write-acceptance-evidenceSkill
- add-cli-commandSkill
- check-the-line-ending-before-patchingSkill
- cut-a-releaseSkill
- keep-docs-en-pt-paritySkill
- ledger-abandoned-entries-are-ledger-onlySkill
- read-the-grammar-through-the-document-modelSkill
- split-an-oversized-specSkill
- stage-a-change-backlogSkill
- triage-holds-work-on-the-machinerySkill
- write-acceptance-evidenceSkill
- doctrina-contextSkill
- doctrina-nextSkill
- doctrina-onboardSkill
- doctrina-statusSkill
- doctrina-whySkill
- doctrina-workSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 91
Every change's structure section (the first of change check) must report ready to apply — its archive-gate section lists the open tasks, …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- doctrina:skill-export — generated from .doctrina/skills/stage-a-change-backlog.md by `doctrina index rebuild`; edit that file, not this one. -->Skill — stage-a-change-backlog
When to use this skill
- A review, audit, or roadmap produced a list of work items and each
one should become a
doctrinachange now, implemented later. - A change must be opened and left parked for the next session.
- More than about three changes will be open at the same time.
Procedure
Measure the context headroom BEFORE opening anything. Open changes are tier
COREinpackages/doctrina-cli/src/commands/context.js: they never degrade and are never dropped, so each one is a permanent subtraction from every capability pack until it archives.for cap in "" $(ls .doctrina/specs); do doctrina context $cap | grep -E "within budget|over budget" doneA scaffolded, empty change costs ~380 tokens; an authored one costs 1200–2000. If the tightest pack is already above ~85%, a backlog of any size will push at least one pack over and
doctrina context <cap>will exit 1 — which fails theContext budget gatejob in CI. Decide what to do about that before opening 20 folders, and say so out loud.- Number the ids so the number carries the priority.
workallocates the next sequentialNNNNon its own, which encodes only arrival order. Pass--id NNNN-slugexplicitly and allocate in priority order, sodoctrina nextandprimelist the backlog in the order it should be drained. Open each change with
--quietand--capability.doctrina work "<the finding, in one or two sentences>" \ --id 0032-short-slug --capability <cap> --title "short title" --quiet--quietprints one line instead of the ~50-line playbook. Without it, N changes print N identical playbooks.--capabilityscaffoldsspecs/<cap>/delta.mdwith**Operation:**prefilled (MODIFIED when the spec exists, ADDED when it does not). Without it no delta is created at all, and a delta with a missingOperationheader is the failure that surfaces days later inanalyze.--titlekeeps the proposal H1 and the slug short while the full prompt still lands under## Why.- Confirm the capability against the spec that actually OWNS the area
first — read each spec's
## Purpose, or its**Source:**header, which names the files it owns (ADR 0027). In this repository:authoringownsintake/work/spec/change/decision/contract/skill/intent/triage;gatesowns the gates and their drivers (close,doctor, the CI pipeline);insightowns the read path (context,search,show,status,prime,handoff,report,why);cliowns the surface itself andnext;scaffoldingownsinit/adapter/templates/hooks/index/upgrade/watch/metrics/completion;templatesowns the shipped templates and the surface block;validationowns the document model.
Plan every change before leaving it.
analyzeFAILS on atasks.mdthat still holds scaffold placeholders (- [ ]with no text), andchange tickrefuses to tick an empty box. "Open it and leave it" is not a state the framework accepts — a parked change is one that is planned and not started:## Whyand## Whatwritten (a heading that survived is not a section that was written —analyzelooks inside).tasks.mdholding real, checkable, unchecked steps.- The delta scaffolded with the right
Operation, body left for the implementing session; make "write the EARS body" the last task.
Verify the whole backlog, not one change.
for d in .doctrina/changes/0*/; do doctrina change check "$(basename "$d")" | grep -m1 "ready to apply" done doctrina validateEvery change's structure section (the first of
change check) must reportready to apply— its archive-gate section lists the open tasks, which is expected for a staged change — andvalidatemust show 0 errors before the session ends.- Write the files whole, not with patches. See
[[check-the-line-ending-before-patching]] — a
.doctrina/file may be CRLF and a\n\n-anchored replacement silently no-ops, which is how six hollow proposals once reached the archive.
Anti-patterns
- Opening the backlog first and discovering the budget wall afterwards.
The measurement in step 1 costs one command; undoing 20 changes costs
20
change abandoncalls and 20 ledger lines. - Leaving
tasks.mdwith the scaffold's three empty boxes "to fill in later".analyze,change checkandcloseall refuse it, so the change is not parked — it is broken. - Letting
workallocate the ids, then trying to communicate priority in the title. The id is whatnext,primeand the ledger sort on. - Opening a change per finding when two or more findings are literally the same edit. One change per closeable unit; group only where the work is genuinely one patch.
Related material
.doctrina/specs/cli/spec.md— theworkandchangecontracts..doctrina/specs/gates/spec.md—analyze,context, and the budget semantics.- ADR 0022 — context assembly is retrieval, not a dump.
- [[triage-holds-work-on-the-machinery]] — why a prompt about the machinery gets held at exit 3.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

