Task: Spike: capture promotion runbook and compass support

Table of Contents

This page documents a task in the Improve cybernetics documentation story. It captures the goal, current status, acceptance, and any notes or results.

Goal

Define the canonical capture→story promotion flow and determine how much of it compass capture promote should automate. Promoting a capture differs from starting a new story in three important ways:

  • The capture's UUID must be inherited by the story (identity continuity — existing id-links stay valid).
  • The story's Goal and Acceptance are populated from the capture's * What and * Why sections, not written from scratch.
  • The capture file must be deleted (git rm) and its row removed from any index file (sprint capture.org, backlog bucket index).

Currently compass capture promote only prints instructions; it does not execute the steps. This spike decides whether to automate it, and in either case produces a runbook the LLM can follow.

Status

Field Value
State DONE
Parent story Improve cybernetics documentation
Now Nothing.
Waiting on
Next
Last touched 2026-05-29

Acceptance

  • [ ] The three distinctions between promotion and new-story creation are documented (UUID inheritance, content population, capture cleanup).
  • [ ] compass capture promote evaluated: current behaviour documented; gap between current and desired behaviour articulated.
  • [ ] A promote_capture_to_story runbook written (or a decision made to automate in compass with a note on what the automation requires).
  • [ ] Recommendation recorded in * Result: automate vs. manual runbook, with rationale and any follow-up tasks created.

Plan

(Transient implementation strategy. Written when work starts; distilled into the parent story's * Decisions and cleared when the task closes. Plans do not outlive their task.)

Notes

PRs

PR Title
#896 [agile] Promote cybernetics docs capture to story; add capture promotion spike

Review

Comment summary File Decision Notes
       

Result

Emacs 29.3 (Org mode 9.6.15)