Idea: Real-time progress markers for orchestrator skills (Option C from #13 analysis)

[aimsise]

Problem

When a user runs a long-running orchestrator skill like /impl (which has a Generator → AC Evaluator → Code Reviewer loop with up to 3 rounds), there is no real-time tracking of where in the loop the work currently is. State is only captured at two narrow points:

1. Compact-state: Written by pre-compact-save.sh when context compaction occurs.
2. Filesystem artifacts: eval-round-N.md and quality-round-N.md files appear at the end of each evaluation phase.

This creates a recovery gap: if a session is interrupted (Ctrl+C, crash, manual /clear) before context compaction triggers, there is no record of what was in progress. /catchup then has to infer state from filesystem artifacts alone, which is ambiguous — it cannot reliably distinguish "the loop is still in progress" from "the loop finished, ready for review".

This is the underlying issue captured as item #13 in our internal evaluation: /catchup's phase detection is stateless and re-derives everything from the filesystem each time.

Proposal

Introduce a real-time progress marker file at .backlog/active/{slug}/.in-progress.yaml that orchestrator skills update at each step.

Marker format

skill: impl
phase: generator      # or ac-evaluator | code-reviewer | dry-run | done
round: 2
started_at: 2026-04-10T10:30:00+09:00
last_updated: 2026-04-10T10:42:00+09:00

Behavior

1. Orchestrator skills (/impl, /scout, /audit, possibly /create-ticket) write/update the marker at each major step:

   • Phase 1 start → create marker with initial phase
   • Each round start → update round and phase
   • Generator / AC Evaluator / Code Reviewer spawn → update phase
   • Phase 3 reached → delete the marker

2. /catchup reads the marker first:

   • If present → "You were in the middle of <skill> at <phase> (round N). Resume?"
   • If absent → fall back to compact-state and filesystem-based detection

3. Stale marker handling:

   • If last_updated is older than ~24 hours, /catchup warns the user and offers to delete or override.

Benefits

• Highest accuracy: state is recorded at the moment of action, not at compaction time.
• Survives all interruption types: manual /clear, Ctrl+C, process crashes, network failures.
• Phase detection becomes a record lookup, not a heuristic: no more guessing whether a loop is in progress or done.
• Works without context compaction: useful for short sessions that never trigger compaction.

Trade-offs

• Stale marker problem: crashes or aborted sessions leave orphaned markers. Mitigated by age-based cleanup, but adds UX friction (confirmation dialogs).
• Multi-skill change surface: requires modifications to several orchestrator skills (/impl, /scout, /audit, possibly /create-ticket) plus /catchup.
• New file convention: adds .in-progress.yaml to the project's mental model and documentation surface.
• Race conditions: not a problem in single-session use, but could be in concurrent sessions on the same ticket.

Why this is filed as an idea (not implemented yet)

The same underlying problem (#13) is being addressed by a smaller, lower-risk approach first: Option B, which enhances pre-compact-save.sh to emit a YAML frontmatter that /catchup can parse — using the same pattern already established by session-stop-log.sh. Option B solves the four key recovery scenarios (loop interruption, focus tracking, filesystem drift immunity, evaluation round reproduction) with a 3-file change.

This proposal (Option C) is parked here for future consideration. It would be worth revisiting if any of the following become true:

• Long-running skills become longer or more frequent (e.g., 5+ rounds in /impl).
• Users frequently report interruptions before context compaction triggers.
• Concurrent multi-session work on the same ticket becomes a use case.
• Stale-marker UX patterns are explored elsewhere in the project (e.g., a generic .in-progress convention shared by other tools).

Discussion welcome on whether this approach has merit, or whether we should take it in a different direction (e.g., a centralized state file rather than per-ticket markers).