docs(skill): harden SKILL.md into a bug-prevention guardrail - #11
Merged
Conversation
Turns SKILL.md from advisory into an enforceable gate, codifying every bug class we actually hit shipping Tiers 1-4 so they can't recur. Added: - The Iron Laws — 8 non-negotiables up front (proof-before-ship, 3x suite, never break a passing test, additive-only, zero-dep, reserve ports, code+docs together, clean diff). - Section 9 VERIFY — a hard gate with copy-paste self-audit commands (syntax, zero-dep import check, console.log check, manifest/port validity, diff review), the mandatory 3x full-suite rule, leaked-process check, and a live smoke step per change type. All commands verified to run correctly. - Section 10 'Bugs we will not ship again' — a table of real failures (the 4700/ec2 port collision, the getFreePort EADDRINUSE race, MCP stdout corruption, manifest formatting churn, half-shipped feature, stacked-PR merge gap, refactor behavior drift) each mapped to the rule that prevents it. - Section 11 SHIP — PR hygiene (prefer single PRs to main; verify main actually contains the code after merge; paste verification results in the PR body). - Strengthened section 1 (prove the port is free + not 4600) and section 5 (allocate-and-bind-with-retry port pattern; assert concrete values; clean up to avoid leaks; never paper over flake with sleeps/timeouts).
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.
Make SKILL.md strong enough that we stop pushing bugs
SKILL.md was good advice. This makes it an enforceable gate. Every rule now traces to a real failure we hit shipping Tiers 1–4, with copy-paste commands to catch it.
What's new
The Iron Laws (up front, read every time): 8 non-negotiables — proof-before-ship, run the suite 3×, never break a passing test, additive-only at the boundary, zero runtime deps, reserve ports, code+docs in one commit, clean diff.
§9 VERIFY — the gate you cannot skip. Replaces the soft "run before declaring done" with:
console.logscan, manifest/port validity, diff review) — all verified to run correctly against the current repo.pgrep).§10 "Bugs we will not ship again" — a table of the actual failures from this repo's history, each mapped to the rule that prevents it:
4700/ec2 port collision silently disabled a servicegetFreePort()race → intermittentEADDRINUSE(passed run 1, failed run 3)console.logcorrupted its own JSON-RPC streamseed()shipped for 2 of 4 services but docs implied allmainmainafter merge§11 SHIP — PR hygiene (single PRs to main; verify main actually contains the code post-merge; paste verification results in the PR body).
Strengthened §1 (prove the port is free and ≠
4600) and §5 (the retry pattern for booting multiple servers; assert concrete values; clean up to avoid cross-file leaks; never paper over flake withsleep/timeouts).Verification
Docs-only change. I ran every command embedded in the new sections to confirm they work as written (fixed one zsh glob-quoting issue in the import-audit command). +201/−32 lines, no code touched.
Independent of the feature PRs — safe to merge straight to
main.