Repository navigation
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
pstack covers what happens when an operation runs twice (
make-operations-idempotent), but no principle says what code should do when a dependency hangs, fails, or keeps failing. Without that, agents write calls with library-default timeouts, retry everything at several layers, and drop or block on poison messages. This adds the missing principle and pairs it with the idempotency one: a retry is only safe when the operation converges.What changed
pstack/skills/principle-bound-every-external-call/SKILL.md, in the same shape as the other principles (intro, Why, The idea, The test). It asks for four bounds on every external call: a deadline, a retry policy (transient errors only, idempotent operations only, exponential backoff with jitter, capped, at one layer), a dead-letter path for poison messages, and a circuit breaker.poteto-modeprinciple index (Architecture, right after Make Operations Idempotent), the README table, and the guide's principles list.pstack/README.md,docs/guide/08-principles.md, anddocs/guide/README.md.harness/pstack/claude-codewithscripts/generate-pstack-harness-trees.mjs.Scope
Docs and skill text only. No command, playbook, or script behavior changes. The principle is generic and names no cloud, vendor, or library.
Tradeoffs
The four bounds could live as a section inside
make-operations-idempotent. I kept them separate because the triggers differ: idempotency is about repeated runs of your own operation, and this is about calls into something you don't control. The test section links the two.Blast Radius
Adds one entry to the poteto-mode index, which loads on every poteto-mode run, so it adds one line of context there. No other skill references change.
Verification
node scripts/check-pstack-docs.mjs: tree reports 25 principles, 0 problems.node scripts/generate-pstack-harness-trees.mjs --check: harness up to date.node scripts/validate-plugins.mjs: all plugins validated.