ci-preflight
Skill6 starsChanged 33 days agoMITView on GitHub
Run before pushing any branch that adds shipped files, hooks, or platform-specific code. Prevents the CI-whiplash pattern — multiple red pushes that could have been caught locally.
- Commits and pushes
3 other projects use a version of this.
Adopted by
Most recently taken up by
- n1m21n/Infinitetheir own version, first seen Nov 2, 2026
- Marnie0415/pi-skillstheir own version, first seen Jun 13, 2026
- matteing/opaltheir own version, first seen Feb 16, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- n1m21n/Infinite★ 332same name
- matteing/opal★ 59same name
- Marnie0415/pi-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository79 other files it gives its agents.
- adr-phase-coverageSkill
- aposd-red-flag-reviewSkill
- apple-on-device-aiSkill
- artifact-gatesSkill
- asc-app-create-uiSkill
- asc-build-lifecycleSkill
- asc-cli-usageSkill
- asc-crash-triageSkill
- asc-id-resolverSkill
- asc-localize-metadataSkill
- asc-metadata-syncSkill
- asc-notarizationSkill
- asc-ppp-pricingSkill
- asc-release-flowSkill
- asc-revenuecat-catalog-syncSkill
- asc-shots-pipelineSkill
- asc-signing-setupSkill
- asc-submission-healthSkill
- asc-subscription-localizationSkill
- asc-testflight-orchestrationSkill
- asc-wall-submitSkill
- asc-workflowSkill
- asc-xcode-buildSkill
- choose-boring-technologySkill
- conways-lawSkill
- cost-routingSkill
- cost-tier-routingSkill
- cunninghams-lawSkill
- ddd-strategic-auditSkill
- ddd-tactical-reviewSkill
- debug-test-captureSkill
- developing-ios-appsSkill
- doerrs-lawSkill
- fitts-lawSkill
- fix-regression-guardSkill
- galls-lawSkill
- goodharts-lawSkill
- greenspuns-tenth-ruleSkill
- gsd-core-hooksSkill
- hofstadters-lawSkill
- hyrums-lawSkill
- ios-accessibilitySkill
- ios-simulator-boot-healthSkill
- kerckhoffs-principleSkill
- kernighans-lawSkill
- knuths-optimization-principleSkill
- lady-lovelaces-objectionSkill
- leaky-abstractionsSkill
- linuss-lawSkill
- mobile-ios-designSkill
- money-boundary-judgmentSkill
- moores-lawSkill
- no-deferSkill
- norvigs-lawSkill
- parkinsons-lawSkill
- peter-principleSkill
- postels-lawSkill
- post-fix-traceSkill
- qa-test-architectSkill
- rubber-duckSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 22
Rule: Before pushing any new file that ships to users, run a completeness search.
- Very specific: line 29
Use an existing sibling file as the probe: if gsd-existing-hook.js appears in N files, your new hook must appear in the same N files.
- Distinctive: line 39
The pattern generalises: every repo with drift-guard tests has its own set of registration surfaces.
- Distinctive: line 47
Rule: Run the repo's full test command before every push.
- Very specific: line 54
If the full suite is too slow for every push, run npm test:affected (or the repo's equivalent) — but know what it misses.
- Very specific: line 87
Test-constructed path (via path.join, os.tmpdir, fs.realpathSync)
- Distinctive: line 103
Run through this before every git push on a branch that changes shipped files:
- Distinctive: line 129
When you add a new hook, run all five before pushing.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CI Preflight
A green CI is not a reward for guessing correctly. It's the outcome of a local gate that already ran.
The three CI-whiplash anti-patterns
This skill exists because these three failures happen repeatedly and all have the same root cause: pushing before checking.
Anti-pattern 1: Missing registration surfaces
What happens: A new shipped file (hook, agent, command, module) passes unit tests but fails integration tests because it wasn't added to one of several whitelists/registries/inventories the repo maintains.
Why it's hard: These surfaces are spread across multiple files with no obvious connection — you find one and miss two others.
Rule: Before pushing any new file that ships to users, run a completeness search.
# Find every place "existing-hook.js" is referenced in the repo
grep -r "gsd-existing-hook" . --include="*.js" --include="*.cjs" --include="*.md" --include="*.json" -lUse an existing sibling file as the probe: if gsd-existing-hook.js appears in N files, your new hook must appear in the same N files. Missing even one fails CI.
In this repo, adding a new hook requires updating all of:
hooks/managed-hooks-registry.cjs—MANAGED_HOOKSarrayscripts/build-hooks.js—HOOKS_TO_COPYarraybin/install.js— registration block withfs.existsSyncguardget-shit-done/bin/lib/installer-migration-report.cjs—BUNDLED_GSD_HOOK_FILESSetdocs/INVENTORY.md— headline count + table rowdocs/INVENTORY-MANIFEST.json— runnode scripts/gen-inventory-manifest.cjs --write
The pattern generalises: every repo with drift-guard tests has its own set of registration surfaces. Find them before you write the first line.
Anti-pattern 2: No local test run before pushing
What happens: Tests that would have caught the problem run in CI but not locally. Each failure costs a full CI round-trip (5–15 minutes) instead of a 30-second local run.
Rule: Run the repo's full test command before every push. Not a subset — the full suite.
npm test # or whatever this repo uses
npm run lint # catch lint errors before they hit CIIf the full suite is too slow for every push, run npm test:affected (or the repo's equivalent) — but know what it misses.
⚠️ npm test does not always mirror CI's unit scope. In gsd-core specifically, the default npm test (node scripts/run-tests.cjs) selects a different set than CI's unit job — observed in practice reporting fail 0 locally while CI's unit job failed on inventory-counts. Mirror the CI unit job directly before pushing:
npm run test:unit # mirrors CI's "test (ubuntu, NN)" / "full test" unit scope; catches drift-guard tests npm test can skipSpecific CI gates to run locally before pushing:
npm run lint:changeset # catches missing/malformed changeset
npm run lint:docs # catches missing docs update
node scripts/gen-inventory-manifest.cjs # verify manifest is current
node --test tests/inventory-counts.test.cjs tests/inventory-manifest-sync.test.cjs tests/bug-3628*When you add a new shipped surface, run the drift-guard tests explicitly — they're fast and catch exactly the "I forgot to update the registry" error.
Anti-pattern 3: Guessing at cross-platform fixes
What happens: A test fails on a platform you can't run locally (Windows). You form a hypothesis, push a fix, it fails again. Repeat 3 times.
Why it's expensive: Each guess costs a full 10-minute Windows CI run. Three guesses = 30 minutes of CI time and a messy commit history.
Rule: Diagnose before fixing. Understand exactly what the platform does differently before writing a single line of code.
Diagnosis checklist for cross-platform path failures:
- Read the failure message literally. "Path inside worktree should pass. stderr: (empty)" means the hook is exiting 2 (blocking) when it should pass. The path comparison is producing false negatives, not false positives.
- Identify the data sources. List every path-valued variable and its origin:
- Test-constructed path (via
path.join,os.tmpdir,fs.realpathSync) - Git-returned path (
git rev-parse --show-topleveloutput) path.resolve()outputfs.realpathSync()output On Windows these can differ in: separator (/vs\), case (Runnervsrunner), 8.3 short name vs long name.
- Test-constructed path (via
- Find the mismatch. On Windows,
os.tmpdir()returnsC:\Users\RUNNER~1\AppData\Local\Temp(8.3 short name).fs.realpathSyncexpands to the long name.git --show-toplevelreturns whatever form the working tree was registered under. These three can all differ. - Design for sameness, not normalisation. The fix for "two path values that might not match" is usually to ensure they come from the same source rather than normalising disparate sources into a common form. In this PR: comparing two
git --show-topleveloutputs (same binary, same format) worked; comparingpath.resolvevsrealpathSyncdidn't.
The key insight: Normalisation fights the platform. Sameness of origin avoids the fight entirely.
Pre-push checklist
Run through this before every git push on a branch that changes shipped files:
[ ] npm run test:unit (mirrors CI's unit job — npm test alone can under-cover it; see Anti-pattern 2)
[ ] npm run lint
[ ] If adding a new shipped file:
[ ] Grepped for an existing sibling to find all registration surfaces
[ ] Added to every surface the sibling appears in
[ ] Ran drift-guard tests directly: node --test tests/inventory-*.test.cjs tests/bug-*whitelist*.test.cjs
[ ] If writing cross-platform path code:
[ ] Listed every path variable and its origin (test-constructed / git / path.resolve / realpathSync)
[ ] Identified which sources can diverge on Windows (8.3 names, case, separators)
[ ] Chosen "same source" over "normalise disparate sources"
[ ] No TODOs left in the diff that belong in CIQuick reference: common drift-guard test patterns in this repo
| Test file pattern | What it guards |
inventory-counts | docs/INVENTORY.md headline numbers match filesystem counts |
inventory-manifest-sync | docs/INVENTORY-MANIFEST.json matches filesystem |
bug-3628-bundled-hook-* | BUNDLED_GSD_HOOK_FILES matches hooks/ directory |
bug-1754-js-hook-guard | Every .js hook has fs.existsSync guard in install.js |
managed-hooks | managed-hooks-registry.cjs matches hooks/ directory |
When you add a new hook, run all five before pushing.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

