Skip to content

pause update

Jump to bottom
Ian Smith edited this page May 24, 2026 · 3 revisions

:pause and :update restructure — Design Document

Status: Draft, 2026-05-24.

Summary

progress.md is policy-blocked from upstream push (per :document: "per-session diary is too noisy for the durable record"). But :pause and :update currently write substantive reasoning — mental context, open questions, decisions, dead-ends — into progress.md, where it is trapped locally.

This document restructures both skills so:

  • progress.md keeps only operational state (reproducible from git, pwd, date).
  • Substantive prose moves to findings.md, which :document already pushes upstream as a ticket comment at archive time.

No new upstream-write code paths. The fix uses existing chokepoints.

Problem

The ticket-* skills audit identified two skills writing substantive reasoning into progress.md:

  • :pause — appends Last completed, Next step, Open questions, and Mental context worth preserving (3-5 bullets of hypotheses, decisions, dead-ends).
  • :update — appends Completed since last snapshot, Current state, Next step.

progress.md is explicitly excluded from upstream push by :document. Result: the most reasoning-dense output from :pause is also the most thoroughly trapped locally — the opposite of the traceability policy.

Goal

Re-charter the two files to match their actual purpose without creating new upstream-write paths. :document remains the sole chokepoint to Linear / JIRA / GitHub.

  • progress.md = operational state only. Per-session, noisy, never durable. Fully reproducible from git status, git log, pwd, date, and short-term memory.
  • findings.md = substantive prose. Already pushed upstream by :document as a ticket comment at archive time. Already correctly named.

Non-goals

  • Adding any new upstream-write path. :document stays the sole writer to Linear / JIRA / GH.
  • Backfilling existing progress.md files. The change applies to new invocations only.
  • Restructuring :document, :archive, :plan, :start, :merge, or :pr. They are downstream of this change but unaffected.

Scope

Two SKILL.md files only:

  • ticket-plugin/skills/pause/SKILL.md
  • ticket-plugin/skills/update/SKILL.md

Restructured :pause

A) progress.md — operational only

## Pause $TS
**Branch:** $BRANCH (HEAD: $HEAD)
**cwd:** $PWD
**Working tree:** clean | dirty: N files modified
**Last completed:** <one-line>
**Next step:** <one-line, filename:line if applicable, or "unclear — review last commit">

One line per field. No prose subsections. Reproducible from git + short-term memory.

B) findings.md — substantive prose (conditional)

Append a content-titled section (noun-phrase title, not session-titled) only if substantive new context emerged:

## <Short noun-phrase describing the finding / decision / question>
<2–5 sentences. Hypothesis, decision rationale, dead-end and why, or open question.>

Skip entirely if nothing substantive emerged. The discipline rule, embedded in the skill body:

"If it would still matter to a future engineer who never saw this session, it's a finding — write it. Otherwise it's diary — leave it out."

C) Blocker prompt (auto)

Per the multi-ticket design, :pause always prompts:

"What's blocking you on $TICKET? (Enter 'none' if just stopping.)"

  • Answer none (case-insensitive) or empty: leave state.toml unchanged.
  • Other text: write state = "blocked", blocked_on = <text>, blocked_since = $TS to state.toml.

D) Local-sync push to RAG

After file writes, POST the current findings.md body to the RAG service at /local/sync (per the RAG service design). On connection failure, print a one-line warning and continue — never block the pause.

Restructured :update

A) progress.md — operational only

## Update $TS
**Branch:** $BRANCH (HEAD: $HEAD)
**Working tree:** clean | dirty: N files modified
**Completed since last snapshot:** <one-line>
**Current state:** <one sentence>
**Next step:** <one-line>

B) findings.md — substantive prose (conditional)

Same conditional + content-titled rule as :pause.

C) Local-sync push to RAG

Same as :pause.

Rules to add to both SKILL.md files

In the ## Rules section:

  • Do NOT write reasoning, hypotheses, decisions, or open questions to progress.md. Those go to findings.md as content-titled sections.
  • If unsure whether something is a finding or a diary entry, prefer findings — :document can decide what to push at archive time; trapped diary is unrecoverable.

Acceptance criteria

  1. A typical :pause invocation writes ~6 lines to progress.md and zero-or-more content-titled sections to findings.md.
  2. A :pause that surfaced no new reasoning produces a progress.md entry and no findings.md change.
  3. Reading progress.md standalone tells you where the work was paused. Reading findings.md standalone tells you what was learned.
  4. :document's existing push logic requires no change — new findings ride the existing path.
  5. Neither skill calls Linear / JIRA directly. The local-sync POST is to the RAG service only, and tolerates failures gracefully.

Migration

No backfill. New invocations follow the new template; existing entries in progress.md files stay as-is. The next :archive pushes whatever findings.md currently holds — the right behavior.

If a project has existing progress.md files with reasoning trapped in them, the user can manually move those sections into findings.md before the next archive. No automation provided.

Prerequisites

  • Multi-ticket design — :pause no longer clears CURRENT-$PREFIX (the file no longer exists); selection lives in the git branch. The blocker prompt rule comes from this doc.
  • RAG service design — the /local/sync push relies on the RAG endpoint; calls degrade gracefully.

Neither prerequisite blocks this restructure. The restructure can ship in isolation; without the RAG running, the /local/sync call simply warns and returns.

Clone this wiki locally