Skip to content

Finalise conventions.md and migrate non-conventions into the spec #36

Description

@dilberryhoundog

docs/drafthorse/framework/conventions.md is mid-rewrite. Conventions go from 13 bullets to 7 by folding related entries into super-conventions. This issue closes that rewrite. It blocks the wider spec-alignment sweep.

Settled so far

New or rewritten:

  • Building is difficult, so execution is easy — DraftHorse as a builder's spec.
  • Stepping stones — the step mechanism as one convention, absorbing Steps are universal and Conditions carry routing, with the open-mechanism consequences (loop back, span, dormant, support, handover) as sub-bullets.
  • The error step — two modes: Hard bail and clean up (unrecoverable → clean up the run's mess, end the skill, user repairs across following turns then re-runs or finds the skill no longer needed) and Claim the remainder (recoverable, named in advance → the error step resolves it and the run completes). Absorbs the old claims the remainder.
  • References all data, no work — absorbs inline vs external, naming not explaining, cite at the moment of use.

Untouched: Single source of truth, Sharp Prose, Dynamic Improvement.

Removed, homed elsewhere: A handover fits its parent step, standalone Naming not Explaining, standalone Cite references and Inline vs external.

Remaining work

  • Write the prose for the new convention drafted in shorthand at conventions.md:14-21 — a document must be executable by an agent with no DraftHorse knowledge, leaning on existing markdown notation, consistent shape, separation of concerns, and self-documenting structure.
  • Add the sub-point drafted in shorthand at conventions.md:66 to References all data, no work — citations are always markdown links or harness tools.
  • Migrate three entries out of conventions and into the spec as instructions, each needing a verified home before deletion:
    • Conditions are checkable and exhaustivesteps.md (appears already covered around :77).
    • Gates are compoundsteps.md (appears already covered around :112).
    • Skill Description is invocation-shapedsurfaces.md (unverified).
  • Confirm the handover constraint survives the removal of A handover fits its parent step. The old bullet carried "the finished condition reads the state the handover leaves behind, no handed-back outcome"; Stepping stones states this more weakly, so handover.md must be its home.
  • Resolve the duplication between the Stepping stones sub-bullets and the Step Usage Patterns catalogue in steps.md:141-155. One fact, one home.
  • Delete the archived <!-- +DRAFT: Preserve --> and <!-- Remove --> blocks once their content is confirmed landed.

Also in flight on steps.md

docs/drafthorse/framework/steps.md carries a proposed replacement for the whole ### Dispositions section, left inline as an HTML comment. It aligns the dispositions with the two-mode error step, drops the "default posture for destructive errors" mis-scoping, states "raise an issue" once instead of three times, and bars working steps from carrying dispositions of their own. Review and apply or discard as part of this work.

steps.md:125 also has an unfinished edit — unclosed parenthesis and a stray quote mark.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions