agentleFS
The-Artificer-of-Ciphers-LLCThe-Artificer-of-Ciphers-LLC/skills-from-the-artificer/ci-preflight/SKILL.md

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

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
  1. Distinctive:

    Rule: Before pushing any new file that ships to users, run a completeness search.

    line 22
  2. Very specific:

    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.

    line 29
  3. Distinctive:

    The pattern generalises: every repo with drift-guard tests has its own set of registration surfaces.

    line 39
  4. Distinctive:

    Rule: Run the repo's full test command before every push.

    line 47
  5. Very specific:

    If the full suite is too slow for every push, run npm test:affected (or the repo's equivalent) — but know what it misses.

    line 54
  6. Very specific:

    Test-constructed path (via path.join, os.tmpdir, fs.realpathSync)

    line 87
  7. Distinctive:

    Run through this before every git push on a branch that changes shipped files:

    line 103
  8. Distinctive:

    When you add a new hook, run all five before pushing.

    line 129

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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" -l

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. Missing even one fails CI.

In this repo, adding a new hook requires updating all of:

  • hooks/managed-hooks-registry.cjs — MANAGED_HOOKS array
  • scripts/build-hooks.js — HOOKS_TO_COPY array
  • bin/install.js — registration block with fs.existsSync guard
  • get-shit-done/bin/lib/installer-migration-report.cjs — BUNDLED_GSD_HOOK_FILES Set
  • docs/INVENTORY.md — headline count + table row
  • docs/INVENTORY-MANIFEST.json — run node 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 CI

If 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 skip

Specific 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:

  1. 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.
  2. 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-toplevel output)
    • path.resolve() output
    • fs.realpathSync() output On Windows these can differ in: separator (/ vs \), case (Runner vs runner), 8.3 short name vs long name.
  3. Find the mismatch. On Windows, os.tmpdir() returns C:\Users\RUNNER~1\AppData\Local\Temp (8.3 short name). fs.realpathSync expands to the long name. git --show-toplevel returns whatever form the working tree was registered under. These three can all differ.
  4. 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-toplevel outputs (same binary, same format) worked; comparing path.resolve vs realpathSync didn'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 CI

Quick reference: common drift-guard test patterns in this repo

Test file patternWhat it guards
inventory-countsdocs/INVENTORY.md headline numbers match filesystem counts
inventory-manifest-syncdocs/INVENTORY-MANIFEST.json matches filesystem
bug-3628-bundled-hook-*BUNDLED_GSD_HOOK_FILES matches hooks/ directory
bug-1754-js-hook-guardEvery .js hook has fs.existsSync guard in install.js
managed-hooksmanaged-hooks-registry.cjs matches hooks/ directory

When you add a new hook, run all five before pushing.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.