stack-gotchas
Skill0 starsChanged 56 days agoMITView on GitHub
Use when hitting a known failure in my stack — release-please or a stuck release, a GitHub Pages deploy that won't land, a gh CLI / PAT / Dependabot / npm-resolution dead end, a CodeQL alert that won't close, a Google AI key that only works for one API, Supabase egress or RLS, a Flipper FAP that won't build or refresh, WSL and host-OS oddities (disk, registry, Docker context), or a remote box hanging on a prompt — for a direct diagnose-and-recover recipe.
In this repository14 other files it gives its agents.
- arch-barSkill
- commsSkill
- context-budgetSkill
- exploit-huntSkill
- gdprSkill
- gen-umlSkill
- perf-barSkill
- postmortemSkill
- security-barSkill
- spec-intakeSkill
- stacksSkill
- standardsSkill
- task-flowSkill
- ux-barSkill
The file
Files
stack-gotchas
Overview
Diagnose-and-recover recipes for failures I've actually hit. Each is symptom → what it
really means → fix — not a tutorial. The recipes live in references/, one file per
family; this page is the symptom index. Match the symptom, open that file, apply the
recipe.
Find the symptom
| It looks like | Open |
A release didn't cut; the release PR is stuck, looping, forbidden, or a Release-As: vanished | references/release-please.md |
| A Pages deploy is rejected, queues forever, times out near 600 s, or every retry says cancelled | references/github-pages.md |
| It only breaks inside WSL, the disk won't shrink, or an image or container seems to have vanished | references/wsl.md |
| Egress blown, anonymous writes possible, or fields vanishing after another client writes | references/supabase.md |
| A FAP won't build or test, the catalog rejects it, or its screen stays blank | references/flipper.md |
| Personal data is reachable, or data leaves to a third party undisclosed | references/gdpr.md |
A gh command dies on a GraphQL error, a 403 on a repo I don't own, or a poll loop that never ends | references/github-cli.md |
| The README CI badge says failing while every PR and merge is green | references/github-cli.md |
| The same CodeQL alert keeps coming back, or won't close after a fix | references/codeql.md |
| A Google API key works for Gemini but not for Speech, or the reverse | references/ai-providers.md |
A dependency bump merges without CI, won't install, never goes green, breaks tsc on Node types, or a fork could auto-merge | references/dependencies.md |
| A command on a remote box hangs with no output, or a process match kills the wrong thing | references/remote-ops.md |
| A scheduled job can't fetch a source that answers fine from home | references/ci-network.md |
What belongs here
Failures actually hit, with what the symptom really meant and what fixed it. Not
prevention, not conventions, not a tutorial — those live in the lenses and in stacks. A
recipe with no scar behind it makes every other recipe less trustworthy.
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.