From 0c8b5b852e64714155fff3df79fe63b2bd891ef8 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Sun, 19 Apr 2026 19:00:32 -0700 Subject: [PATCH] Remove internal incident reference from paperclip-dev skill Rewrite the 'Why this Matters' section to remove the PAPA-81 story since this skill will be open-sourced. The key rationale (agent shell servers die between heartbeats) is folded into rule #1 instead. --- skills/paperclip-dev/SKILL.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/skills/paperclip-dev/SKILL.md b/skills/paperclip-dev/SKILL.md index 19f37263059..cb14c3bf4b3 100644 --- a/skills/paperclip-dev/SKILL.md +++ b/skills/paperclip-dev/SKILL.md @@ -174,7 +174,7 @@ eval "$(npx paperclipai worktree env)" # skip if using the primary instance tmux new-session -d -s 'pnpm dev' # Example with a descriptive name: -tmux new-session -d -s papa81-auth-3102 'pnpm dev' +tmux new-session -d -s auth-fix-3102 'pnpm dev' ``` ### Managing the session @@ -197,14 +197,10 @@ curl -sf http://127.0.0.1:/api/health && echo "Server is up" lsof -nP -iTCP: -sTCP:LISTEN ``` -### Why this matters - -In PAPA-81, the dev server was started with `pnpm dev` directly from the agent shell. It appeared healthy during the heartbeat, but died as soon as the heartbeat exited. QA repeatedly found the port unreachable seconds later. Switching to a detached `tmux` session solved the problem — the server survived across heartbeats and remained available for manual testing. - ### Key rules -1. **Always use `tmux` (or equivalent)** when a dev server needs to stay running after the heartbeat ends. -2. **Name the session descriptively** — include the issue or worktree name and port (e.g., `papa81-auth-3102`). +1. **Always use `tmux` (or equivalent)** when a dev server needs to stay running after the heartbeat ends. A server started directly from the agent shell will die when the heartbeat exits, even if it appeared healthy moments before. +2. **Name the session descriptively** — include the worktree name and port (e.g., `auth-fix-3102`). 3. **Verify the server is listening** before reporting the URL to anyone. 4. **Do not use `nohup` or `&` alone** — these are unreliable for agent shells that may have their entire process group killed. 5. **Clean up when done** — kill the tmux session when the testing is complete.