ci-repair
Skill49 starsChanged 14 days agoApache-2.0View on GitHub
Diagnose, isolate, and repair broken CI/CD workflows and red trunk gates across GitHub Actions, spine-invariance, ci-fast, architest DAG rules, structural policies, scorecard freshness, and build breakages. Uses parallel subagents for failure triage, isolated leaf implementation, on-device witness verification, and atomic commit landing. Call when CI turns red, when `fak sync push` or `fak commit --push` is blocked by `COMMITTED_RED`/`CI_BASE_RED`, or when dual-repo synchronization is wedged.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- maximilienGilet/skillstheir own version, first seen Nov 15, 2026
- 2012geek/skillstheir own version, first seen Oct 17, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- 2012geek/skills★ 13same name
- maximilienGilet/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 repository151 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- llms-full.txtllms.txt
- llms.txtllms.txt
- agent-readinessSkill
- appeal-scoreSkill
- bottleneck-mapSkill
- claim-repro-scoreSkill
- clear-out-wipSkill
- commit-cleanSkill
- conflation-scoreSkill
- cross-validateSkill
- curate-clusterSkill
- debt-cleanSkill
- debt-orchestratorSkill
- disambiguation-scoreSkill
- dojo-rsi-scoreSkill
- dos-dispatch-loopSkill
- dos-dispatchSkill
- dos-next-upSkill
- dos-replanSkill
- dos-witness-claimSkill
- field-borrowSkill
- fleet-waveSkill
- git-subagent-syncSkill
- goalSkill
- guard-rsi-scoreSkill
- harness-creatorSkill
- harness-gardenSkill
- industry-scoreSkill
- issue-orchestratorSkill
- issue-queueSkill
- issue-triageSkill
- lightgap-scoreSkill
- memory-compactSkill
- milestone-scoreSkill
- modularizeSkill
- negframe-scoreSkill
- opencode-waveSkill
- operator-heaviness-scoreSkill
- persona-scoreSkill
- phased-planSkill
- plan-auditSkill
- quality-scoreSkill
- question-loopSkill
- refresh-cachedoc-numbersSkill
- refresh-readmeSkill
- releaseSkill
- resume-watchdog-auditSkill
- run-it-all-nightSkill
- score-2xSkill
- scorecardSkill
- scout-loopSkill
- signal-firstSkill
- skill-lifecycleSkill
- skill-overlapSkill
- skill-scoreSkill
- slop-scoreSkill
- sota-checkSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 4 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 37
Never batch unrelated CI fixes into a kitchen-sink commit.
- Distinctive: line 39
Never assume a fix works because "the code looks clean." Reproduce the failure first using the exact command CI executes, implement the …
- Distinctive: line 41
When dispatching concurrent repair workers, assign each worker a mutually disjoint file set.
- Very specific: line 43
Never loosen the architest tier table to resolve an upward import.
- Distinctive: line 44
Never suppress policy rules without structural AST deciders.
- Very specific: line 45
Never silently delete non-secret env reads without updating admittedPostFreeze or moving them to the config surface.
- Very specific: line 47
Always land commits using fak commit --path or fak sweep --apply.
- Very specific: line 53
When diagnosing failed runs from gh run list and gh run view <id> --log-failed, classify errors into one of six canonical categories:
- Very specific: line 132
Verify lane availability with dos arbitrate:
- Very specific: line 163
If racing against peer commits, fak sync push automatically retries fast-forward rebases up to the budget.
- Very specific: line 181
If the failure is a known deterministic break (e.g., stale concept scorecard or unformatted files), it automatically triggers the …
- Very specific: line 184
When fak commit or preflight encounters COMMITTED_RED:
- Very specific: line 193
When fak-sync repo is wedged by public trunk compilation errors:
- Very specific: line 195
If public fak is red, it suggests or triggers /ci-repair on the public checkout before attempting to fast-forward the private mirror.
- Very specific: line 198
When a headless coordinator catches an EXIT_TRUNK_RED error:
- Very specific: line 200
If free, it acquires the ci lane lease, executes the bounded /ci-repair packet, verifies trunk health, and resumes the overnight issue wave …
≈ “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-repair — Triage, Isolate & Repair Red CI/CD Workflows on Trunk
Deterministic, evidence-backed protocol for rapidly converting red CI/CD workflows and broken trunk gates into verified green runs across both public fak and private fak-private. Decomposes compound CI failures into atomic root causes, arbitrates disjoint write sets, dispatches parallel subagents for implementation, verifies on-device test witnesses, and lands explicit-path commits without peer collision.
When to Invoke
- GitHub Actions Red Alert:
Any core CI workflow (
spine-invariance,ci-fast,ci,garden,build-matrix,security-audit) fails onmainor in an active PR. - Push & Synchronization Blockers:
fak commit --pushorfak sync pushfails withCOMMITTED_RED,CI_BASE_RED,TRUNK_CLOSED, or pre-push hook rejection.fak sync drainbecomes stuck in exponential backoff because the upstream trunk has a broken commit.
- Dual-Repository Wedges (
fak-private):fak-sync repofails fast-forward verification because publicfakdoes not compile, has broken tests, or fails boundary checks (fak-boundary check). - Automated Loop Escalation:
Headless super-loops (
super-loop,run-it-all-night,fleet-wave) encounter an unrecoverable red trunk and need to heal the mainline before continuing unattended waves.
Non-Negotiable Invariants
- One Root Cause, One Issue, One Commit:
Never batch unrelated CI fixes into a kitchen-sink commit. Decompose compound failures into distinct concerns (e.g., an architest upward import vs. an adjudicator structural policy vs. a stale scorecard README) and commit each under its own issue and leaf stamp
(fak <leaf>). - Witness-First Verification: Never assume a fix works because "the code looks clean." Reproduce the failure first using the exact command CI executes, implement the minimal remedy, verify on-device exit code 0, and cross-validate with an independent subagent before committing.
- Tree-Disjoint Worker Boundaries: When dispatching concurrent repair workers, assign each worker a mutually disjoint file set. No two workers may concurrently edit the same package or files on the shared trunk.
- Preserve Architectural Invariants:
- Never loosen the architest tier table to resolve an upward import; invert the dependency via a registration seam (
Register...) or push the shared type down a layer. - Never suppress policy rules without structural AST deciders; ensure remedy text does not self-refute by matching its own deny regex.
- Never silently delete non-secret env reads without updating
admittedPostFreezeor moving them to the config surface.
- Never loosen the architest tier table to resolve an upward import; invert the dependency via a registration seam (
- Safe Synchronization:
Always land commits using
fak commit --pathorfak sweep --apply. Always push usingfak sync push(which safely retries transient non-fast-forward races and refuses destructive merges).
Systematic Failure Taxonomy & Remedies
When diagnosing failed runs from gh run list and gh run view <id> --log-failed, classify errors into one of six canonical categories:
Category A: Architest & Layered-DAG Violations (internal/architest)
- Upward Import (
TestNoUpwardImports):- Symptom:
layered-DAG import rule violated: <pkgA> -> <pkgB>. Rule: tier(A) >= tier(B). - Remedy: Invert the dependency. Define an interface or function type in the lower tier (e.g.
type ContentScreener func(body []byte) boolininternal/mcpbroker), provide aRegister...hook, and wire it from a higher-tier package (e.g.internal/headroom/admit.go).
- Symptom:
- Unregistered Engine ID (
TestSingleEngineDriverPerID):- Symptom:
engine id "X" is registered by [P] in non-test code but is not a declared id in engineDriverRole. - Remedy: Add
"X": {"P": "role description"}toengineDriverRoleininternal/architest/architest_test.go.
- Symptom:
- Off-List Self-Registration (
TestRequestPathLeavesRegistered):- Symptom:
leaf P self-registers (init() -> abi.Register*) but is neither blank-imported in internal/registrations nor on regOffList. - Remedy: Add
"P": truetoregOffListininternal/architest/architest_test.go.
- Symptom:
- Non-Literal Subprocess Exec (
TestRequestPathInterpreterFree):- Symptom:
request-path package P calls exec with a non-literal program argument.... - Remedy: Add
"P": "justification"tointerpreterExecAllowininternal/architest/architest_test.go.
- Symptom:
- Missing Third-Party Tool Inventory (
TestThirdPartyEffectsRegisterCoversTree):- Symptom:
the tree pulls in subprocess_tool "X" and docs/sbom/third-party-effects.json has neither a row nor an exclusion. - Remedy: Add
"X"underclass: "subprocess_tool"in alphabetical order indocs/sbom/third-party-effects.jsonwith"pin": "host_provided".
- Symptom:
- Declared Reason Missing Code Emitter (
TestEveryDeclaredReasonHasAnEmitter):- Symptom:
dos.toml declares [reasons.X] but no non-test source contains the token. - Remedy: Define
const ReasonX = "X"in the declaring package and wire it into the producer's refusal/status path.
- Symptom:
- Brittle Test Sleeps (
TestNoBrittleSleepsInAuditedPackages):- Symptom:
brittle time.Sleep synchronization in test; use channels, sync.WaitGroup, or bounded retry/polling loops. - Remedy: Replace
time.Sleep(...)with channel synchronization orselect { case <-time.After(...): }.
- Symptom:
Category B: Policy & Structural Surface Rules (internal/adjudicator, internal/policy)
- Unrecognised Structural Rule (
TestEveryShippedStructuralRuleIsRecognised):- Symptom:
tool "X" arg "command" ships a deny_regex with no structural decider and no inventory entry. - Remedy: Implement a structural AST/command parser in
internal/adjudicator/<rule>.go(e.g.isGitPushArgRule,commandExecutesGitPush), wire it indecide_argpredicates.go, and register it inpolicy_structural_surface_test.gounderfamilies.
- Symptom:
- Self-Refuting Remedy Text (
TestEveryShippedDenyRuleNamesARemedy):- Symptom:
the fix text for regex MATCHES its own deny_regex, and this rule has NO structural decider. - Remedy: Add the structural decider to the
decidedboolean inpolicy_structural_surface_test.goso inert mentions in commit messages, greps, or quoted text are admitted without re-tripping the rule.
- Symptom:
Category C: Generated Artifact & Scorecard Freshness (concept freshness, docs/)
- Disambiguation Scorecard Drift:
- Symptom:
concept generated-artifact freshnessfails with{"verdict":"stale","stale_paths":["docs/concept-disambiguation-scorecard/README.md"]}. - Remedy: Regenerate via
go run ./cmd/fak concept generate, then verify withgo run ./cmd/fak concept freshness --check --json. Commit under lane(fak docs).
- Symptom:
Category D: Uncommitted Companion WIP / Compiler Breakages (COMMITTED_RED)
- Missing Struct Field / Method:
- Symptom:
X undefined (type T has no field or method X). - Remedy: Check the working tree for uncommitted companion edits from peer sessions, or implement the missing exported field/method with appropriate doc comments and tests.
- Symptom:
Category E: Ratchet & Debt Ledgers (internal/envconfiglint, CONFIG_NOT_ENV)
- Unrecorded Non-Secret Env Read:
- Symptom:
env read X is not a declared secret; move it to the config surface (CONFIG_NOT_ENV). - Remedy: If the read landed during an unmonitored window, record
"X"inadmittedPostFreezeininternal/envconfiglint/admitted.goand verify withgo test ./internal/envconfiglint.
- Symptom:
Category F: Formatting & Line Hygiene (gofmt)
- Unformatted Go Source:
- Symptom:
gofmt: N file(s) not formatted (run 'gofmt -w .' from fak/). - Remedy: Format the specific affected files with
gofmt -w <paths>, verify withgofmt -l <paths>, and commit viafak commit --path.
- Symptom:
Step-by-Step Execution Workflow
Phase 1: Triage & Failure Capture
- List recent workflow runs:
gh run list --limit 15 - Inspect failed workflow jobs:
Or examine specific failed job logs:gh run view <run_id> --log-failedgh run view --job=<job_id> --log - Partition failures: Group failures into distinct, non-overlapping concerns (Category A through F).
Phase 2: Advance Ticketing & Arbitration
- Create dedicated GitHub issues:
For each distinct failure category:
gh issue create --title "fix(<subsystem>): <concise summary>" --body "Problem: ... Intended outcome: ... Witness: ..." - Arbitrate lane leases:
Verify lane availability with
dos arbitrate:dos arbitrate --lane <lane> --mode exclusive
Phase 3: Parallel Subagent Delegation
- Assign disjoint write sets:
Launch concurrent
workersubagents for independent failure components.- Worker 1: e.g.
internal/mcpbroker/...,internal/headroom/admit.go - Worker 2: e.g.
internal/adjudicator/git_push.go,internal/adjudicator/... - Worker 3: e.g.
docs/concept-disambiguation-scorecard/README.md
- Worker 1: e.g.
- Execute on-device witness commands:
Each worker must execute and return clean witness command output (e.g.
go test -v ./internal/architest -run TestNoUpwardImports).
Phase 4: Independent Cross-Validation
- Dispatch a
cross-validatorortestersubagent to execute the full affected test matrix independently before landing. - Confirm zero regressions on related packages.
Phase 5: Atomic Staging, Commit & Push
- Lint subject before commit:
fak commit --preview --path <p1> --path <p2> -m "fix(<lane>): <msg> #<issue> (fak <lane>)" - Commit explicit paths:
fak commit --path <p1> --path <p2> -m "fix(<lane>): <msg> #<issue> (fak <lane>)" - Safe sync and push:
If racing against peer commits,fak sync pushfak sync pushautomatically retries fast-forward rebases up to the budget.
Phase 6: Post-Push CI Verification
- Monitor new workflow runs triggered by the push:
gh run list --limit 5 - Watch until
spine-invariance,ci-fast, andcicomplete green.
Integration with Automated Processes & Loops
To keep unattended fleets moving when CI breaks, other processes interact with /ci-repair as follows:
1. The fak sync drain Recovery Hook
fak sync drain queues commits stranded when the upstream trunk is red. Instead of passive exponential backoff that deadlocks on a permanent trunk break:
- On attempt 2 (
attempts >= 2),fak sync draininspectsgh run list --workflow ci-fast. - If the failure is a known deterministic break (e.g., stale concept scorecard or unformatted files), it automatically triggers the deterministic healing pass (
fak concept generate/gofmt -w), commits the fix, and flushes the drain queue.
2. fak recover COMMITTED_RED
When fak commit or preflight encounters COMMITTED_RED:
fak recover COMMITTED_REDprovides executable recovery:
which invokes thefak recover COMMITTED_RED --execute/ci-repairdiagnostics and suggests the exact remediation command.- A red can be pre-existing: test step only, identical on the landing base, and witnessed per
commit-clean"Pre-existing red". In that case, land first under that rule without asking (operator policy 2026-09-26), then triage or file the trunk red separately.
3. Dual-Repo Sync (fak-sync repo in fak-private)
When fak-sync repo is wedged by public trunk compilation errors:
fak-sync repoautomatically runs boundary and compilation probes (fak validate --mine,go work sync).- If public
fakis red, it suggests or triggers/ci-repairon the public checkout before attempting to fast-forward the private mirror.
4. Headless Super-Loops (run-it-all-night, fleet-wave, super-loop)
When a headless coordinator catches an EXIT_TRUNK_RED error:
- It checks
dos arbitrate --lane ci. - If free, it acquires the
cilane lease, executes the bounded/ci-repairpacket, verifies trunk health, and resumes the overnight issue wave without terminating.
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.

