agentleFS
GCarin1GCarin1/Doctrina/.agents/skills/stage-a-change-backlog/SKILL.md

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).

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
  1. Very specific:

    Every change's structure section (the first of change check) must report ready to apply — its archive-gate section lists the open tasks, …

    line 91

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- 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 doctrina change 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

  1. Measure the context headroom BEFORE opening anything. Open changes are tier CORE in packages/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"
    done

    A 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 the Context budget gate job in CI. Decide what to do about that before opening 20 folders, and say so out loud.

  2. Number the ids so the number carries the priority. work allocates the next sequential NNNN on its own, which encodes only arrival order. Pass --id NNNN-slug explicitly and allocate in priority order, so doctrina next and prime list the backlog in the order it should be drained.
  3. Open each change with --quiet and --capability.

    doctrina work "<the finding, in one or two sentences>" \
      --id 0032-short-slug --capability <cap> --title "short title" --quiet
    • --quiet prints one line instead of the ~50-line playbook. Without it, N changes print N identical playbooks.
    • --capability scaffolds specs/<cap>/delta.md with **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 missing Operation header is the failure that surfaces days later in analyze.
    • --title keeps 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: authoring owns intake/work/spec/change/decision/ contract/skill/intent/triage; gates owns the gates and their drivers (close, doctor, the CI pipeline); insight owns the read path (context, search, show, status, prime, handoff, report, why); cli owns the surface itself and next; scaffolding owns init/adapter/templates/hooks/ index/upgrade/watch/metrics/completion; templates owns the shipped templates and the surface block; validation owns the document model.
  4. Plan every change before leaving it. analyze FAILS on a tasks.md that still holds scaffold placeholders (- [ ] with no text), and change tick refuses 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:

    • ## Why and ## What written (a heading that survived is not a section that was written — analyze looks inside).
    • tasks.md holding 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.
  5. 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 validate

    Every change's structure section (the first of change check) must report ready to apply — its archive-gate section lists the open tasks, which is expected for a staged change — and validate must show 0 errors before the session ends.

  6. 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 abandon calls and 20 ledger lines.
  • Leaving tasks.md with the scaffold's three empty boxes "to fill in later". analyze, change check and close all refuse it, so the change is not parked — it is broken.
  • Letting work allocate the ids, then trying to communicate priority in the title. The id is what next, prime and 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 — the work and change contracts.
  • .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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.