Origin
Surfaced by a doc-reviewer smoke-test of extensions/skills/drafthorse/SKILL.md (see #19). Verdict revise, four forcing findings. Three of them are one knot.
The knot
+Gather Requirements captures Mode — a new build, or a conversion of an existing document (with the path to it) — and Terms glosses it. No later step branches on it: no start condition, finished condition, or engagement reads the value. A reader cannot tell what behaviour the mode is meant to select.
The consequence lands in +Draft the Skill, whose only write instruction is "Copy SKILL Template to the destination and fill it". In conversion mode the destination is normally the path of the document being converted, so a literal read overwrites the source before it has been filled. The reviewer's cold walk had to guess between overwriting in place, writing to a sibling path, backing up first, or drafting elsewhere and swapping.
Items
- Wire Mode to behaviour, or drop it. Either name the concrete deltas conversion mode imposes at the steps that own them, or drop Mode from the requirements and the glossary and let the source document be captured as source material alone.
- State the conversion write convention in
+Draft the Skill — where the draft is written relative to the source, and what becomes of the original. If Mode survives, +Gather Requirements should capture destination in a form that distinguishes source path from output path.
- Define the executor document.
+Gather Requirements offers executor-only as an invocation surface, and the Conventions Digest grants executor documents permission to fold the error drain into a reporting step rather than write a standalone error step. Neither the term nor the qualifying condition appears in the body, references, or Terms, so the surface cannot be selected correctly and the exemption cannot be applied.
Also from the same review
- Gates are unmarked.
Agent Invariants forbids proceeding past a gate without the user's approval of that phase's artifact, but no step is marked as a gate. It is inferable from finished conditions that mention approval, and +Fill Reference Gaps and +Draft the Skill sit ambiguously — one names approval in its finished condition, one does not. Two agents could gate at different points. Fix by making gatehood explicit: a named list, or a consistent marker in the finished condition of every gated step.
Acceptance
An agent given only SKILL.md and the prompt "convert this existing SKILL.md to the DraftHorse framework" runs the conversion to a finished draft without inventing a policy for the source file, and without needing framework knowledge the document failed to supply.
Origin
Surfaced by a
doc-reviewersmoke-test ofextensions/skills/drafthorse/SKILL.md(see #19). Verdictrevise, four forcing findings. Three of them are one knot.The knot
+Gather Requirementscaptures Mode — a new build, or a conversion of an existing document (with the path to it) — andTermsglosses it. No later step branches on it: no start condition, finished condition, or engagement reads the value. A reader cannot tell what behaviour the mode is meant to select.The consequence lands in
+Draft the Skill, whose only write instruction is "Copy SKILL Template to the destination and fill it". In conversion mode the destination is normally the path of the document being converted, so a literal read overwrites the source before it has been filled. The reviewer's cold walk had to guess between overwriting in place, writing to a sibling path, backing up first, or drafting elsewhere and swapping.Items
+Draft the Skill— where the draft is written relative to the source, and what becomes of the original. If Mode survives,+Gather Requirementsshould capture destination in a form that distinguishes source path from output path.+Gather Requirementsoffersexecutor-onlyas an invocation surface, and theConventions Digestgrants executor documents permission to fold the error drain into a reporting step rather than write a standalone error step. Neither the term nor the qualifying condition appears in the body, references, orTerms, so the surface cannot be selected correctly and the exemption cannot be applied.Also from the same review
Agent Invariantsforbids proceeding past a gate without the user's approval of that phase's artifact, but no step is marked as a gate. It is inferable from finished conditions that mention approval, and+Fill Reference Gapsand+Draft the Skillsit ambiguously — one names approval in its finished condition, one does not. Two agents could gate at different points. Fix by making gatehood explicit: a named list, or a consistent marker in the finished condition of every gated step.Acceptance
An agent given only
SKILL.mdand the prompt "convert this existing SKILL.md to the DraftHorse framework" runs the conversion to a finished draft without inventing a policy for the source file, and without needing framework knowledge the document failed to supply.