pipeline-reflection-ux

Pipeline Reflection UX Use this skill to keep pipeline/reflection output concise, explicit, and low-noise. Workflow Make Step 0 visible in router narration. Emit Step 0 completion before TaskList() . Emit a one-line reflection outcome with report path. Batch late post-pipeline notifications into one summary. Keep guardrail semantics unchanged ( block stays block ). Required Checks Add/adjust tests before behavior changes. Confirm no regression in routing/taskupdate/read-safety tests. Verify debug-log counts improve for repeated violations/noise. Iron Laws ALWAYS emit Step 0 narration (pending reflections count) before any TaskList() call — omitting the narration makes reflection spawning invisible to the user and breaks the pipeline audit trail. NEVER batch reflection spawns with tool calls that depend on their results — reflection agents must complete before the router proceeds to routing; mixing them creates race conditions. ALWAYS emit a one-line reflection outcome (report path + summary) after reflection-agent completes — without this, the user cannot distinguish a completed reflection from a skipped one. NEVER emit one status message per late-completing background agent — per-agent late notifications create noise storms; batch all late completions into one summary after drain gate passes. ALWAYS preserve existing block semantics when modifying pipeline narration — changing guardrail modes while fixing UX copy conflates two concerns and masks the behavioral impact of either change. Anti-Patterns Anti-Pattern Why It Fails Correct Approach Omitting Step 0 narration Reflection spawning invisible to user; pipeline audit trail broken Always emit "Step 0: N pending reflections..." before spawning reflection agents Missing one-line reflection outcome User cannot distinguish completed reflection from skipped one Emit report path + one-line summary after every reflection-agent completion One status message per late-completing agent Creates noise storms; clutters pipeline output Batch all late completions into one summary message after drain gate passes Changing guardrail modes while fixing UX copy Conflates two changes; behavioral impact of each masked in review Separate UX copy changes from guardrail mode changes in distinct commits Emitting Step 0 completion after TaskList() Violates router output contract; narration out of sequence Emit "Step 0 complete." before calling TaskList(), not after Memory Protocol (MANDATORY) Before starting: Read .claude/context/memory/learnings.md After completing: New pattern → .claude/context/memory/learnings.md Issue found → .claude/context/memory/issues.md Decision made → .claude/context/memory/decisions.md ASSUME INTERRUPTION: If it's not in memory, it didn't happen. References Detailed UX review: references/ui-reflection-review.md Troubleshooting runbook: .claude/docs/TROUBLESHOOTING.md Task tracking protocol: .claude/docs/@TASK_TRACKING_GUIDE.md