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 (
blockstaysblock).
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
blocksemantics 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