Skip to content

Critique: commit-workflow-infographic.png

Summary

The infographic conveys the rough left-to-right shape of the shared commit workflow (xprompt inputs → stop hook → commit skill → sase commit → CommitWorkflow → three output branches), and the three output cards on the right are correct and easy to read. The provider note ("VCS providers: Git, GitHub, Mercurial") and the title are also accurate.

The main problems are with the central CommitWorkflow band: it omits two stages, drops one of the canonical labels in favor of an off-spec synonym, and renders the stages in the wrong relative order. The conflict-resume loop is also drawn ambiguously enough that a new reader cannot tell which step it re-enters. These are accuracy issues a reader checking the diagram against docs/commit_workflows.md or the code would notice immediately.

What's actually in the rendered PNG

Reading the committed commit-workflow-infographic.png directly:

  • Title: Shared Commit Workflow
  • Left input stack: #commit, #propose, #pr (rendered as map-pin icons).
  • Linear path: Agent changes → Stop hook → Commit skill → sase commit → CommitWorkflow (large central band).
  • CommitWorkflow band chips, in the order shown: Precommit, Bead handling, Plan handling, PR tags, Parent detection, VCS dispatch, Tracking, Result marker.
  • Side loop, drawn under the band as a yellow warning chip with a curved arrow: Conflict checkpoint + resume.
  • Right output branches (3 cards):
  • Commit hash + COMMITS entry
  • Saved diff + COMMITS entry
  • PR URL + ChangeSpec
  • Bottom-right note card: VCS providers: Git, GitHub, Mercurial.

Clarity issues a new user would hit

  1. xprompt inputs are not labeled as xprompts. The three location-pin icons on the left are labeled only with #commit / #propose / #pr. A reader who has never seen an xprompt has no cue that these are xprompt triggers — they look like tags or hashtags. A small caption ("xprompts") above the stack would land the concept.
  2. Order inside the CommitWorkflow band is ambiguous. The chips sit in a single horizontal row inside the band with no internal arrows or numbering. The eye reads them left-to-right, but several of them are not actually in left-to-right execution order (see accuracy section). A new user trying to follow "what runs first?" will get the wrong answer.
  3. The conflict loop's re-entry point is unclear. The yellow chip sits below the band with a small curved arrow, but the arrow does not visibly target a specific stage. From docs/commit_workflows.md and CommitWorkflow.resume(), resume re-enters at provider vcs_finalize_commit (post-dispatch) and then replays the post-dispatch tracking steps. The diagram should show the loop landing between VCS dispatch and Result marker / Tracking, not floating under the whole band.
  4. "Tracking" is one chip but represents several discrete outputs. A reader sees one chip and three output cards and has to guess which card each tracking step writes to. Splitting "Tracking" into the actual tracking artifacts (ChangeSpec, COMMITS entry, result marker) — or showing arrows from each tracking sub-step to its specific output card — would remove the ambiguity.
  5. No visual distinction for proposal-skipped stages. The doc explicitly calls out that bead lifecycle and plan handling are skipped for create_proposal, but every chip looks identical. A subtle styling cue on those two chips ("skipped for #propose") would match what the doc already documents and is one of the most user-asked questions.

Accuracy issues vs. code and doc

Grounding against src/sase/workflows/commit/workflow.py (run method, lines 104–226) and the stage list in docs/commit_workflows.md ("3. CommitWorkflow orchestrates"):

  1. Wrong relative order in the band. The actual execution order from the code is:
  2. Bead lifecycle (handle_beads) — skipped for proposals
  3. Plan handling (handle_sase_plan) — skipped for proposals
  4. Precommit (run_precommit)
  5. PR name suffixing (compute_suffixed_cl_name) — PR only
  6. Parent detection (detect_parent_changespec) — PR only
  7. PR tags / body (apply_project_pr_prefix, append_pr_tags, build_pr_body) — PR only
  8. Diff capture (capture_pre_commit_diff)
  9. Checkpoint (checkpoint_save)
  10. VCS dispatch
  11. Tracking (ChangeSpec for PR; result marker; COMMITS entry for commit/propose)

The diagram puts Precommit first, then Bead handling, then Plan handling. That contradicts the prompt sidecar's own corrected instruction ("Put bead lifecycle and plan handling before precommit"), and contradicts the doc and code, which both run beads/plan before the precommit hook so plan files are staged when just fix (or whatever precommit is configured) runs.

  1. Missing "Bead lifecycle" — replaced with "Bead handling". The doc's canonical name (and the prompt's required label) is Bead lifecycle. The diagram shows Bead handling. Terminology drift; should match the doc and prompt.
  2. Missing "Diff capture" chip. This is a real stage in the code (capture_pre_commit_diff, line 177 of workflow.py) and is in the prompt's required label list. Without it, a reader cannot tell where the Saved diff + COMMITS entry output branch's diff actually comes from.
  3. Missing "Checkpoint" chip. The pre-dispatch checkpoint write (checkpoint_save(cp), line 192 of workflow.py) is what the Conflict checkpoint + resume side loop is reading from. Omitting the chip leaves the conflict loop floating without a clear origin point.
  4. Missing PR-only "PR name suffixing" stage. The doc lists this explicitly under PR-only stages, and the code computes _<N> suffixing in run (lines 124–140) before parent detection. Not in the prompt label list either, but worth flagging since it's a real PR-only stage that affects the output branch (PR URL + ChangeSpec).
  5. Stop-hook → commit-skill description is under-specified. The arrow from Stop hook straight to Commit skill glosses over a real branch in the code: when SASE_BEAD_ID is set, the stop hook first asks the agent to close/verify the bead before invoking the commit skill (per docs/commit_workflows.md "Stop Hook" section, points 4–5). Probably too detailed for the band, but worth a small annotation.
  6. Output branches are correct but the proposal branch is mislabeled imprecisely. "Saved diff + COMMITS entry" matches the doc and code (proposals append a COMMITS entry per workflow.py _run_tracking_steps and the doc's "Tracking: Appends a proposal COMMITS entry"). No change needed; flagging only that this was the chip most likely to drift.

Concrete suggested changes for regeneration

For the next phase (sase-2s.12 — Regenerate diagram: commit-workflow):

  1. Use the canonical 10-stage chip list, in execution order, inside the CommitWorkflow band, with internal left-to-right arrows or numeric prefixes so order is unambiguous: Bead lifecycle → Plan handling → Precommit → PR tags → Parent detection → Diff capture → Checkpoint → VCS dispatch → Result marker → Tracking. (This matches the prompt sidecar's "Exact visible labels" list verbatim.)
  2. Mark proposal-skipped chips visually — a small "(skipped for #propose)" caption or a dashed border on Bead lifecycle and Plan handling.
  3. Mark PR-only chips visually — a small "(PR only)" caption or accent on PR tags and Parent detection.
  4. Anchor the conflict-resume loop to specific stages. The arrow should leave VCS dispatch (on conflict) and re-enter at Checkpoint → VCS dispatch (after manual resolve), then continue through Result marker and Tracking. Drawing the loop as an explicit arc between those two chips, instead of a floating side card, makes the resume model legible.
  5. Label the input stack as xprompts so #commit / #propose / #pr read as a category, not as floating tags.
  6. Keep the right-side three-card output branches and the "VCS providers: Git, GitHub, Mercurial" note — both are accurate and readable as-is.
  7. Rename "Bead handling" → "Bead lifecycle" to match the doc and prompt.
  8. Optional but helpful: add a small label on the Stop hook → Commit skill arrow noting "blocks agent + selects skill" so the stop hook's role as a gate is visible at a glance.

These changes bring the diagram back into alignment with both docs/commit_workflows.md and the actual CommitWorkflow.run() implementation, and address the highest-impact clarity gaps.