triage-holds-work-on-the-machinery
Skill1 starsChanged 4 days agoMITView on GitHub
Recognise when the lane classifier holds an authoring task as RUNTIME because of its nouns, and decide between --force, --chore and an actual diagnosis. Use when: `doctrina work` exits 3 with \"hold: this reads as a RUNTIME problem\", or a prompt about workflows, CI, metrics, logs, secrets or selectors is about to be scaffolded.
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
- stage-a-change-backlogSkill
- 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
- write-acceptance-evidenceSkill
- doctrina-contextSkill
- doctrina-nextSkill
- doctrina-onboardSkill
- doctrina-statusSkill
- doctrina-whySkill
- doctrina-workSkill
The file
Files
<!-- doctrina:skill-export — generated from .doctrina/skills/triage-holds-work-on-the-machinery.md by `doctrina index rebuild`; edit that file, not this one. -->Skill — triage-holds-work-on-the-machinery
When to use this skill
doctrina work "<prompt>"exits 3 and printshold: this reads as a RUNTIME problem, not a change of behaviour.- The prompt is about building or documenting the observability, CI, release, metrics, or configuration machinery — as opposed to diagnosing it.
The distinction the classifier is trying to draw
classify() in packages/doctrina-cli/src/commands/triage.js scores a
prompt against three weighted term sets and holds the request when
RUNTIME wins by a margin of two or more. The hold exists for a real
reason: a broken workflow used to become a change with a proposal,
tasks and a spec delta — ceremony spent on a diagnosis, and a close that
attested to nothing.
But the RUNTIME and CHORE signal lists match domain nouns, and the
PRODUCT list only partly compensates with authoring verbs
(declare, document, record, specify, define). So a prompt that
is unambiguously authoring work still gets held whenever it names enough
machinery. Observed, in one session of opening 20 changes, all three
holds were false:
| Prompt (abridged) | Held on | Actually |
| move the playbooks into overridable templates | config, wiring | authoring |
make the ledger a readable source for report and review | logs, metrics | authoring |
| metrics and the usage log feed the flow | logs, config | authoring |
Procedure
- Answer one question: is the spec wrong, or is the running system
wrong?
- The requirement is missing or must change → PRODUCT →
--force. - The requirement exists and only the implementation moves →
CHORE →
--chore(no EARS delta, and no hold either). - Something is wired, empty, or ran nothing → RUNTIME → do not scaffold. Diagnose.
- The requirement is missing or must change → PRODUCT →
If it is a diagnosis, follow the hold. It is right more often than it is wrong:
doctrina triage "<prompt>" # the lane, plus the runtime checks doctrina contract check # declared wiring vs the workflow doctrina verify # the real build gateOpen a change only once the diagnosis shows the requirement itself is missing.
If it is authoring, force it and say why.
doctrina work "<prompt>" --id NNNN-slug --capability <cap> --force--forceis the documented escape and the hold's own message points at it. It is not a workaround.- Prefer rewording only when the reworded prompt is still honest.
Leading with an authoring verb — "declare…", "document…", "record…",
"specify…" — usually clears the hold, because those verbs carry
weight 3 in the PRODUCT list. Do not bend the prompt away from what
the change actually is just to please the classifier: the prompt
lands verbatim under
## Whyand is the change's provenance. - Record the disagreement if the project tracks it. The lane the change was opened in — and whether a human overrode it — is the only data that calibrates this classifier at all.
Anti-patterns
- Treating exit 3 as "the prompt is bad" and rewording it in circles. Exit 3 is the PRECONDITION class: the work may be perfectly valid, this project has simply not been diagnosed yet.
- Reaching for
--choreto dodge the hold on work that genuinely needs a spec delta.--choreskips the delta steps entirely; needing one later means it was never a chore. - Assuming a held prompt is wrong. The hold is a hint
with the same status as the capability guess in
work— arguable, not authoritative.
Related material
- ADR 0024 — a request is classified into a lane before it is scaffolded.
- ADR 0023 — the runtime surface is declared, never inferred.
packages/doctrina-cli/src/commands/triage.js— the three signal lists and the margin rule.- [[stage-a-change-backlog]] — where this trap shows up once per change in a row.
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.

