shell-init-side-effect-gating

Skill: Shell Init Side-Effect Gating

When to load

Trigger when:

• User asks to add or modify .zshrc / .zshenv / .zprofile / .zlogin / .bashrc / .bash_profile
• User shows a [N] PID job notification or other unexpected background process on shell login
• User asks to silence a [N] PID notification (audit first, don't just slap &! on it)
• Reviewing existing shell init for cleanup or refactor

Steps

1. Find all & in shell init:

   grep -nE '&\s*$' ~/.zshenv ~/.zshrc ~/.zprofile ~/.zlogin 2>/dev/null
   

2. For each backgrounded process, identify its consumer (RPROMPT, prompt segment, alias, key binding, function called from elsewhere).

3. Check the consumer's gate — is it conditional on a marker file, TTY, $DISPLAY, uname, etc.?

4. Compare gates:

   • Consumer gated, side effect not → leak
   • Both gated the same way → fine
   • Both ungated → fine
   • Side effect gated, consumer not → consumer might be missing optimization

5. Decide on fix (in this priority order):

   • A. Move side effect to consumer's entry point (e.g., wrapper function) — preferred
   • B. Apply same gate to side effect — if gate is static at source time
   • C. Silence with &! — only if leak is acceptable and noise is the only complaint
   • D. Make consumer unconditional — only if re-evaluating design intent confirms broad usefulness

6. Verify:

   zsh -c 'source ~/.{{AGENT_NAME_LOWER}}/.zshrc_aliases; sleep 0.3; jobs -l' 2>&1
   

   Should report no jobs (or only the ones you intended).

7. Document the change in P4-cortex/growth/patterns/shell-init-side-effect-gating.md.

Anti-patterns

• ❌ Adding & "for performance" without checking the consumer's gate
• ❌ Slapping &! on every & to silence notifications
• ❌ Treating [N] PID as "noise to silence" — it's a symptom pointing at a real issue
• ❌ Moving the side effect to a wrapper without checking that the wrapper actually gates the consumer