Pitfall Explorer

Fix: Fix

Fix: Validate redirect_uri against registered callback URLs

Fix: Restrict permissions

Fix: Restrict socket permissions to docker group only

Fix: Create branch before rebase

Fix: Add auth middleware

Fix: Use external volumes (volumes: mydata: external:true) or avoid docker-compose down -v which removes named volumes

Fix: Authenticate with docker login or configure a registry mirror in /etc/docker/daemon.json

Fix: Check if the process needs a TTY: add tty:true in compose or -t flag. Also check entrypoint vs cmd

Fix: Use docker-compose up --build instead of docker-compose build + up to only rebuild changed services

Fix: Add healthcheck with pg_isready (Postgres) or mysqladmin ping, and use condition: service_healthy

Fix: Use host.docker.internal (Mac/Windows) or --network=host (Linux) instead of 127.0.0.1

Fix: Use user: "${UID}:${GID}" in compose or chown on host directory to match container user

Fix: Check that the WebSocket route doesn't have competing HTTP route on same path; WebSocket negotiation needs explicit websocket_route

Fix: Use Query(None) instead of plain None: Optional[str] = Query(default=None)

Fix: Ensure CORSMiddleware is added BEFORE any route definitions, and check that allow_origin_regex doesn't conflict

Fix: Use UploadFile with .read() in chunks, or set Starlette's maximum request size via app.add_middleware

Fix: Use dependency injection with forward references (from __future__ import annotations) or restructure into a shared service layer

Fix: Enable response_model validation with response_model_by_alias=False or return dict instead of mismatched ORM object

Fix: Use asyncio.create_task() or a task queue (Celery/arq) for truly async background work

Fix: Use page.waitForURL('**/target-path') or waitForSelector on a post-navigation element

Fix: Use page.locator(selector).click({force:true}) or wait for visibility with waitFor({state:'visible'})

Fix: Set page.setViewportSize({width:1920, height:1080}) to match target viewport

Fix: Register page.on('dialog', dialog => dialog.accept()) before navigating to pages with alerts

Fix: Wait for page.waitForLoadState('networkidle') before taking screenshots

Fix: Set headless:false temporarily for debugging, or use {visible:true} in locator options

Fix: Create a new browser context per test with browser.newContext() instead of reusing the default context

Fix: Use page.waitForSelector('.selector', {timeout: 10000}) or page.waitForFunction() for JavaScript-rendered elements

Fix: none

Fix: y

Fix: y

Fix: y

Fix: Minimum QA: open page in browser, check console for JS errors, submit form and verify results render. Use headless browser for agent-built tools, not just curl.

Fix: After deploying fixes behind Cloudflare: purge cache, test against origin IP bypassing Cloudflare, or add Cache-Control: no-cache during dev. Verify on origin before blaming Cloudflare.

Fix: Dont trust curl -I for content-type checks on FastAPI. Use curl -s (GET). Consider middleware to fix HEAD content-type if CDN behavior matters.

Fix: Never nest quote escaping across Python→JS boundaries. Use data attributes and this.dataset.query instead of embedding strings in onclick. Serve complex JS as separate .js file.

Fix: Add @app.post("/") alias alongside named routes on FastAPI. Handles stripped path from nginx while keeping named route for direct access.

Fix: Match JS fetch URLs and nginx location blocks exactly. Add @app.post("/") aliases since nginx strips path prefixes.

Fix: test fix

Fix: Do not delete the session CWD directory while the agent is active. If you need to scaffold a fresh project, `cd` away first or do it in a subdirectory.

Fix: Avoid this condition. Terminal with `workdir=/tmp` still fails — the CWD check happens before `workdir` is evaluated.

Fix: skill creation bypasses CWD but file writes do not.

Fix: not try it.

Fix: When collapsing multiple domains to a single portal: (1) scrub internal language from live pages first, (2) set up redirects, (3) delete dead files, (4) update docs (AGENTS, README, llms.txt, sitemaps, deploy.sh), (5) clean nav of dead links, (6) deploy and verif...

Fix: n't bypass without extreme cause.

Fix: Avoid this condition. `Agentic Flow` is retired. Grep and purge all variants from all files.

Fix: Avoid this condition. Internal strategy must never leak. Rankings, prioritization, barrier analysis, competitive positioni

Fix: Avoid this condition. nginx specs needs `autoindex on` — without it, 403 Forbidden.

Fix: Avoid this condition. Bastion CSS brace rules: Public landing uses regular string (single braces). Admin uses f-string (do

Fix: Avoid this condition. Bastion Gateway is not public-facing. Public landing redirects to `.dev`. Admin portal at `/admin?ad

Fix: Don't reference dead domains in outreach, docs, or code. No `.io`, no blueprint registry, no badges.

Fix: They're FastAPI endpoints in `main.py` — `GET /robots.txt` returns `text/plain`, `GET /sitemap.xml` returns `application/xml`. No static file to deploy.

Fix: include the unit: `date('now', '-N days')`.

Fix: Wrangler scans parent directories for wrangler.toml files — a Pages deploy will fail if it finds a Worker config with `route`.

Fix: Newly created A records may not resolve immediately.

Fix: Avoid this condition. 521 errors = SSL mode. If Cloudflare proxies show 521, the SSL/TLS mode is likely "Full" but the ori

Fix: Create them first via Cloudflare API or dashboard.

Fix: Avoid this condition. PyYAML: If any API uses `yaml.safe_load()`, remember to `pip install pyyaml` separately — it's not a

Fix: `python3` not `python3.11` in deploy scripts for VPS.

Fix: Run `wrangler pages deploy` from `/tmp/` or another neutral directory to avoid picking up Worker configs from project directories.

Fix: n't try to deploy FastAPI to Workers — use a VPS instead.

Fix: Avoid this condition. Telegram flood control on media. Sending >3 images in rapid succession triggers rate-limiting with a

Fix: use `MEDIA:/absolute/path` inline in message text. Markdown image syntax only works for URLs, not local paths.

Fix: Avoid this condition. Bastion Gateway is not included in default screenshot runs (internal ops, not public-facing). When t

Fix: not invent content, do not add sections you think are implied. Ask directly.

Fix: Avoid this condition. Screenshots go to `/tmp/wwa-screenshots/` — create dir if missing.

Fix: Avoid this condition. .com/blueprints/ is a redirect to workswithagents.io — no need to screenshot it separately.

Fix: Avoid this condition. .io uses port 8500 (was previously Bastion). Bastion Gateway is separate and runs on its own port wh

Fix: run `pkill` with `background=true` and poll for completion before starting new servers. Start each server ind...

Fix: Use `headless=True` for Playwright — the terminal session may not have display access. `screencapture` CLI fails in headless contexts.

Fix: Avoid this condition. When all sites are deployed, skip the server restart step and capture directly from live URLs. This

Fix: localhost only during development.

Fix: Vilius prefers light default. Capture dark as secondary view.

Fix: `~/.hermes/hermes-agent/venv/bin/python`, not `python3.11`. System python3.11 does not have playwright installed.

Fix: Pages change. After adding new .com pages (learn, newsletter, blog, contact, about), the sites list must include them. Check `ls .com/*.html` before building the script. Current default includes all .com sub-pages plus .co.uk, .dev, and .io landing pages.

Fix: `background=true` and `notif...

Fix: Avoid this condition. Multi-pass reviews find more — first pass catches obvious bugs, second pass catches

Fix: Avoid this condition. Silent exceptions (`except Exception: pass/continue`) — auto-flag these. Full detection

Fix: Avoid this condition. Auto-fix introduces new issues — counts as a new failure, cycle continues

Fix: Avoid this condition. Lint tools not installed — skip that check silently, don't fail

Fix: Avoid this condition. No test framework found — skip regression check, reviewer verdict still runs

Fix: if reviewer flags something intentional, note it in fix prompt

Fix: retry once with stricter prompt, then treat as FAIL

Fix: Avoid this condition. Large diff (>15k chars) — split by file, review each separately

Fix: Avoid this condition. Not a git repo — skip and tell user

Fix: Avoid this condition. Empty diff — check `git status`, tell user nothing to verify

Fix: Avoid this condition. If the repo already has some files, only add missing ones — don't replace without asking.

Fix: `git shortlog -sn` instead.

Fix: Don't copy-paste template verbatim without filling in project-specific details.

Fix: Don't add ELI5 sections. They're patronizing for production repos.

Fix: Use `external-project-quality-sop` as the audit rubric. The SOP defines the 5-pillar standard (Brand, Operations, Content, Package, Code Quality). An audit that doesn't map findings to these pillars misses the framework the user expects. After reading all files, structure the report using the...

Fix: Avoid this condition. "Pupils rule" — scanners flag patterns, not intent. When grep-based security/quality scans fire on a

Fix: When spec files or other checked artifacts are renamed (e.g., `handoff-protocol.md` → `handoff.md`), the audit script's filename checks become stale and report false positives — the file exists but under a different name. When re...

Fix: Avoid this condition. .gitignore missing. Projects without `.gitignore` will commit `.venv/`, `__pycache__/`, `.env`, and

Fix: README says "MIT" or "CC BY 4.0" in the license section but no `LICENSE` file exists on disk. GitHub sidebar will show "License: None" — a legal exposure and contributor deterrent. 🚨 Critical. The audit must grep README for license claims and...

Fix: Not every project directory is initialized with `git init`. Check for `.git` directory existence. A project with no git history has never been committed — no version control, no rollback, no collaboration. 🚨 Critical. Also check that the GitHub repo URL in READM...

Fix: they time out at 600s, cannot use `session_search`, `web_search`, or `read_file` reliably, produce hallucinated analysis, and waste 500+ seconds per ta...

Fix: When new SDK modules are added, `__init__.py` must import the ACTUAL class name from the module, not an aspirational one. Run `grep "^class " sdk/python/workswithagents/*.py` to get the real exports. Actual names: TrustScoreClient, Deploy...

Fix: FastAPI cannot run on Cloudflare Workers. deploy.sh lines like `cd .dev && npx wrangler deploy` will always fail. The correct pattern is hybrid: static sites → Cloudflare Pages, APIs → Hetzner VPS via rsync+ssh.

Fix: Any `wrangler.toml` in static site dirs (.com, .co.uk) must be deleted. Pages fails validation with "Configuration file for Pages projects does not support route." In API dirs (.dev, .io, Bastion), wrangler.toml with `main = "api/main.p...

Fix: "Built Bastion and Works With Agents solo" erases Pelin's co-owner role. Check the founders section of every llms-full.txt for ownership accuracy.

Fix: When domains are added (like .io), AGENTS.md often doesn't get updated. The audit must verify the domain table lists all active domains and the deploy count matches.

Fix: The UK mirror's llms.txt is not on the main editing path — it doesn't get updated when .com pages change. Every audit must check that .co.uk/llms.txt says "Live" not "Specification — not yet live," lists actual HTML pages (not phantom .md files), and ha...

Fix: Avoid this condition. Dead code patterns: See `references/dead-code-enum-pattern.md` for the `if False` enum masking antip

Fix: After wiping old brand references from the repo and memory, check `~/.hermes/project-ledger/projects/` for entries under the old name. Delete them — they contain stale tasks (buy old domain, old pricing, old legal steps).

Fix: Avoid this condition. Check for orphaned files. A `website/` directory with a full sales page that doesn't match the decla

Fix: Avoid this condition. Watch for dead code masking missing enums. `ActionType.ASSIGNMENT if False else ActionType.NOTIFICAT

Fix: Check if deploy scripts reference projects/DBs that don't exist yet. A deploy.sh that can't run is a critical gap.

Fix: Run `grep` for retired brand names, old URLs, deprecated product names across the entire repo AND ~/.hermes/memories/ AND ~/.hermes/BRAND.md.

Fix: Check for files that don't match the declared architecture (e.g., a dark-theme sales page in a project that uses light theme).

Fix: Don't sugarcoat. "Course has 0% content built" is more useful than "content is in development."

Fix: Don't assume alignment. The core value of an audit is finding what disagrees.

Fix: Don't stop at surface level. Reading README + a few files isn't an audit. Read everything.

Fix: n't skip files because you read them last time. First pass catches surface contradictions, second pass catches subtle mismatches, third pass catches edge cases and orphaned references. Each pass sh...

Fix: Avoid this condition. Rebuild the TUI (`npm --prefix ui-tui run build`) before testing — tsx watch mode may lag on first l

Fix: Avoid this condition. After adding live UI state, search every consumer of the old prop/helper and thread the new state th

Fix: Avoid this condition. `cli_only=True` commands won't work in gateway/messaging platforms — unless you add a `gateway_confi

Fix: Avoid this condition. For commands with subcommands, ensure the `subcommands` tuple in `CommandDef` matches what's in the

Fix: Make sure any aliases are properly registered in the `aliases` tuple — no other file changes are needed, everything downstream (Telegram menu, Slack mapping, autocomplete, help) derives from it

Fix: Don't forget to set the appropriate category for the command in `CommandDef` (e.g., "Session", "Configuration", "Tools & Skills", "Info", "Exit")

Fix: Avoid this condition. dev.to canonical URL must be full URL: `https://blog.workswithagents.dev/slug` not just `/slug`. Ret

Fix: Avoid this condition. Hashnode body format: Don't send YAML frontmatter in `contentMarkdown` — it gets rendered as code bl

Fix: always verify publish success via the API response, not by curling the blog UR...

Fix: pre-clean: `re.sub(r'[^a-z0-9\s-]', '', title.lower()); re.sub(r'\s+', '-', slug)[:65].strip('-')`. Don't rely on ...

Fix: Avoid this condition. dev.to rate limiting: Returns 429 with "try again in 30 seconds". Sleep 35s and retry.

Fix: Verify with a GET request.

Fix: Avoid this condition. dev.to User-Agent required: Requests without `User-Agent` header get HTTP 403.

Fix: Avoid this condition. dev.to tags format: Array of strings, lowercase. Max 4 tags.

Fix: Slug must be lowercase, hyphenated.

Fix: Avoid this condition. Credential names: `hashnode API` and `dev.to API` — note the space and capitalisation. `dev.to` (no

Fix: Set `canonical_url` on dev.to articles pointing back to Hashnode.

Fix: Avoid this condition. Rate limits: Hashnode ≈1 req/sec, dev.to ≈3 req/sec. Sleep 1.2s between bulk imports.

Fix: Set unique slugs.

Fix: Avoid this condition. dev.to frontmatter in body: API rejects or garbles articles with YAML frontmatter. Strip with Python

Fix: To schedule, create as draft (published: false) and use a one-shot cron job to flip it to published: true at the desired time.

Fix: Avoid this condition. Body fix via PUT: If the published body is garbled (only closing line remains, frontmatter leaked),

Fix: , skip everything until the first `---` separator after the title/byline block. The safe...

Fix: Avoid this condition. Canonical URL: Set for cross-posting attribution. Points to workswithagents.com for the canonical ve

Fix: Set `"published": false` to save as draft.

Fix: lowercase.

Fix: check with a separate GET request to verify the article was published.

Fix: use Python for body extraction.

Fix: ALWAYS strip with Python, never sed.

Fix: use `dev.to API` first. The skill's CRITICAL section at the top exists because this mistake happens every session.

Fix: Avoid this condition. Article closings that promise too much — Never "I'll be back tomorrow" or "Part 3 Friday." When a fo

Fix: Avoid this condition. Dead brand references — Never name dead domains (agenticflow.dev) or old branding (origami) in artic

Fix: Vilius fact-checks every claim. Verify or leave out.

Fix: Avoid this condition. False choice: Never frame lessons as "capable X beats incapable Y." That's obvious. Frame as the non

Fix: Avoid this condition. Too much detail: Model names, quantization levels, CLI commands — cut them. The insight survives wit

Fix: Avoid this condition. Fake cadence: Never say "I'll be back tomorrow." Say "Part N+1 coming soon" only if it's written. Ot

Fix: with PUT.

Fix: the `---` separator as the anchor — skip everything until you hit it, then take the rest.

Fix: Avoid this condition. Handle contradictions explicitly — don't silently overwrite. Note both claims with dates,

Fix: Avoid this condition. Rotate the log — when log.md exceeds 500 entries, rename it `log-YYYY.md` and start fresh.

Fix: Avoid this condition. Ask before mass-updating — if an ingest would touch 10+ existing pages, confirm

Fix: a wiki page should be readable in 30 seconds. Split pages over

Fix: Add new tags to SCHEMA.md

Fix: Avoid this condition. Frontmatter is required — it enables search, filtering, and staleness detection.

Fix: Every page must

Fix: Don't create pages for passing mentions — follow the Page Thresholds in SCHEMA.md. A name

Fix: Always update index.md and log.md — skipping this makes the wiki degrade. These are the

Fix: Always orient first — read SCHEMA + index + recent log before any operation in a new session.

Fix: sources are immutable. Corrections go in wiki pages.

Fix: Do not create a developer-only comparison if the user asked for board/C-suite handoff.

Fix: Do not omit governance for agentic AI; tool permissions are often the real risk.

Fix: Do not overstate precise prices without checking current primary sources.

Fix: Do not make the report vendor-marketing-heavy.

Fix: Do not bury the recommendation under raw source notes.

Fix: Avoid this condition. If a zip code alone gives ambiguous results globally, include country/state

Fix: Avoid this condition. `distance` and `directions` use `--to` flag for the destination (not positional)

Fix: Avoid this condition. Overpass API can be slow during peak hours; the script automatically

Fix: Avoid this condition. OSRM routing coverage is best for Europe and North America

Fix: Avoid this condition. `nearby` requires lat/lon OR `--near "<address>"` — one of the two is needed

Fix: Avoid this condition. Nominatim ToS: max 1 req/s (handled automatically by the script)

Fix: Avoid this condition. Rate limits are per base, not per token. 5 req/sec on `baseA` and 5 req/sec on `baseB` is fine; 6 re

Fix: A `403` on one base while another works means the token's Access list doesn't include that base — not a scope or auth issue. Send the user to https://airtable.com/create/tokens to grant it.

Fix: Writing `"Status": "Shipping"` when `Shipping` isn't in the field's option list errors with `INVALID_MULTIPLE_CHOICE_OPTIONS` unless you pass `"typecast": true` (which auto-creates the option).

Fix: Avoid this condition. PATCH vs PUT. `PATCH` merges supplied fields into the record. `PUT` replaces the record entirely and

Fix: A missing `"Assignee"` key doesn't mean the field doesn't exist — it means this record's value is empty. Check the schema (step 3) before concluding a field is missing.

Fix: Python stdlib (pattern above) — never hand-escape.

Fix: Avoid this condition. Max input: 4000 chars (larger inputs are truncated)

Fix: Avoid this condition. Binary/control chars in input are stripped automatically

Fix: Avoid this condition. First call after restart may time out while model loads; retry once with 120s timeout

Fix: Avoid this condition. oMLX must be running (check: `brew services restart omlx` if down)

Fix: Avoid this condition. To quantize: kill oMLX first, run quantization, restart oMLX

Fix: Avoid this condition. oQ4 quantization (`quantize_oq_streaming(oq_level=4)`) needs ~20GB GPU working memory for a 15GB mod

Fix: DO NOT use `omlx launch pi` — same hang as direct pi

Fix: DO NOT run multiple models concurrently — GPU memory fragmentation

Fix: DO NOT try pi with oMLX — hangs indefinitely (Node.js undici issue)

Fix: DO NOT load fp16 models (15GB+) — they OOM on 24GB Mac Mini

Fix: it will burn 12+ turns on `ls`/`cat`. Feed it specific error output and say "fix these files."

Fix: stdlib. If an agent needs to run `pip install X` before using the reference implementation, it's too heavy.

Fix: Every spec must answer "how does an agent reading this actually use it?"

Fix: Don't forget the specs index: Every new spec must be added to `specs/index.md` AND `llms.txt`. Agents discover specs through these indices.

Fix: Avoid this condition. nginx 403 = file permissions: nginx worker runs as www-data, not root. Directories need 755, files n

Fix: Verify locally from VPS (`curl localhost -H "Host:..."`). If local=200 and public=404, add `?v=1` cache-bust or wait ~1 hour.

Fix: Avoid this condition. CRITICAL: Write specs directly, NOT via subagents. Local models (AgenticQwen-8B-oQ4) consistently ti

Fix: Avoid this condition. The tunnel URL changes each time you restart it

Fix: Avoid this condition. Save BEFORE risky encounters

Fix: Avoid this condition. Dialog detection via RAM is unreliable — verify with screenshots

Fix: Always add wait_60 x2-3 after door/stair warps

Fix: Always sidestep after exiting buildings before going north

Fix: Do NOT send more than 4-5 actions without checking vision

Fix: NEVER download or provide ROM files

Fix: Avoid this condition. Some packs have env vars to control behavior (e.g., ATM10 uses ATM10_JAVA, ATM10_RESTART, ATM10_INST

Fix: Avoid this condition. Delete the world/ folder to regenerate with a new seed

Fix: Avoid this condition. The pack's startserver.sh often has an auto-restart loop — make a clean launch script without it

Fix: Avoid this condition. If online-mode=false, set enforce-secure-profile=false too or clients get rejected

Fix: Avoid this condition. "Can't keep up!" warnings on first launch are normal, settles after initial chunk gen

Fix: Avoid this condition. First startup is SLOW (several minutes for big packs) — don't panic

Fix: Avoid this condition. `max-tick-time=180000` or higher — modded servers often have long ticks during worldgen

Fix: ALWAYS set `allow-flight=true` for modded — mods with jetpacks/flight will kick players otherwise

Fix: Avoid this condition. Adding new tools: See `references/adding-a-tool.md` for the step-by-step checklist — module template

Fix: Avoid this condition. Identity requires `cryptography`: The `wwa_identity_verify` tool uses `cryptography.hazmat.primitive

Fix: Avoid this condition. TOOLS dict indentation — nesting bug: When adding new tool definitions to the `TOOLS` dict in `serve

Fix: Avoid this condition. Rate limits: None currently. All local data sources — sub-millisecond queries.

Fix: Avoid this condition. Data sources: FactBase reads from `~/.hermes/factbase/facts.db`. Pitfalls from `~/.hermes/skills/*/r

Fix: JSON Schema `"default": false` in Python source must be `"default": False`.

Fix: Avoid this condition. Args stringification: Never use `hermes config set` for MCP server args. Edit YAML directly.

Fix: Wait ~1 hour for cache expiry, or use a cache-busting query param (`?v=1`). Token lacks cache purge permissions. Alternati...

Fix: Avoid this condition. VPS IP: `178.105.85.197` — key-based SSH only, password auth disabled after initial setup.

Fix: Avoid this condition. Wrangler ignores AGENTS.md and .wrangler/: These are not uploaded to Pages — only actual site files.

Fix: Avoid this condition. Credential-proxy service name: It's `cloudflare API` (with spaces, capital letters) — not `cloudflar

Fix: Avoid this condition. 404.html must serve actual 404 status: Simple 404 pages without the right Content-Type handling may

Fix: Avoid this condition. .co.uk is a mirror: Don't duplicate all .com pages into .co.uk. It only has index.html + llms files

Fix: Only API code changes need `systemctl restart`.

Fix: Avoid this condition. Pages project names differ: `.com` → `workswithagents-com`, `.co.uk` → `workswithagents-couk` (no do

Fix: Avoid this condition. Account ID required: Cloudflare account ID `801c0021346323bcf9a9a33c3513669c` must also be set as `C

Fix: Avoid this condition. Cloudflare API token env var: `CLOUDFLARE_API_TOKEN` MUST be set, NOT `CF_API_TOKEN` or anything els

Fix: Avoid this condition. Cloudflare API Token scope — our token (`Cloudflare API Token`) is scoped for Pages + DNS only. It C

Fix: Verify locally from the VPS first: `ssh root@VPS 'curl -sI http://localhost/badges/file.svg -H "Host: domain"'`. If local=200 a...

Fix: `chmod 755 /opt/works-with-agents/.io/badges/ && chmod 644 /opt/works-with-agents/.io/badges/*.svg`

Fix: Avoid this condition. Full deploy skill — load `works-with-agents-deploy` for Cloudflare Pages + all domains

Fix: Avoid this condition. Facts are in FactBase — query `curl "https://workswithagents.dev/v1/facts?entity=vps"` or `?entity=d

Fix: Avoid this condition. Python version on VPS — 3.11 (service uses venv at .dev/venv/ and .io/venv/)

Fix: Avoid this condition. If systemctl restart hangs — check `journalctl -u wwa-dev -n 20` for startup errors

Fix: Avoid this condition. rsync trailing slashes matter — `api/` syncs contents, `api` would create api/api/

Fix: Avoid this condition. Doc changes don't need restart — only api/main.py changes do

Fix: cancelling/adding/completing many tasks requires one call per task. For batches of 10+, use a Python script with direct SQLite writes.

Fix: `context-add` CLI uses `--type dir|file` but the schema column is `file_type`. When inserting directly, use `file_type`.

Fix: `session-start` always uses `datetime('now')`. To backdate a session, insert directly: `INSERT INTO sessions (project_id, started_at, ended_at, notes) VALUES (<pid>, '<ISO>', '<ISO>', '<notes>')`

Fix: If reasons are needed, update the database directly: `UPDATE tasks SET description = description || ' [Cancelled: reason]' WHERE id = <id>` then `task-cancel <id>`

Fix: Avoid this condition. No `session-list` command — query `SELECT * FROM sessions WHERE project_id = <id>`

Fix: Avoid this condition. Context files point at directories that no longer reflect the active codebase

Fix: Avoid this condition. Tasks describe a strategy (e.g., "course-first") while commits show a different one (e.g., "standard

Fix: Avoid this condition. Ledger's last session is days old but repo has fresh work

Fix: Avoid this condition. Ledger shows 9 pending tasks but git log shows 30+ commits

Fix: Avoid this condition. `create_app_with_agents(...)` ← doesn't exist

Fix: Avoid this condition. `AdkWebServer(...)` ← needs 7 manual dependencies (agent_loader, session_service, memory_service, et

Fix: Avoid this condition. `get_fast_api_app(agents_dir=..., web=True)` ← CORRECT, used by `adk web` CLI

Fix: Avoid this condition. Existing rules may block catch-all creation. If a default disabled drop rule exists (priority: 21474

Fix: Once the wildcard `*@domain.com` rule is in place, `hello@`, `support@`, `pelin@` etc. all forward automatically — no need to create them as separate destination addresses.

Fix: If `verified: null`, check the destination inbox for a Cloudflare verification email.

Fix: `{field: "to", type: "literal", value: "*@domain.com"}` instead.

Fix: The token must have both `Addresses:Edit` and `Rules:Edit` permissions.

Fix: Avoid this condition. `Email Routing Addresses:Edit` is NOT enough to enable Email Routing. Enabling requires a one-time d

Fix: use account-level (`/accounts/{id}/email/routing/addresses`) for creating destination addresses. Zone-level POST returns 405 "Method not allowed for this authentication scheme."

Fix: Avoid this condition. UI GIFs smaller: Flat design compresses well (~300KB for 11 frames).

Fix: Triple-check escaping when writing Playwright scripts.

Fix: Avoid this condition. Plain strings without variables: use `{}` → `"scrollTo({top: 0, behavior: 'smooth'})"`

Fix: Avoid this condition. UI frame duration: 1000-1500ms per frame for dashboards (more visual detail vs CLI). Panels with tab

Fix: Mixing them causes JS SyntaxError. Check whether the string is an f-string before deciding.

Fix: verify with `grep -n "goto"` after editing.

Fix: Avoid this condition. UI GIFs smaller: Flat design compresses well (~170KB for 9 frames).

Fix: Avoid this condition. Large CLI GIFs: ~600KB raw. ffmpeg palette optimization reduces to ~400KB.

Fix: Avoid this condition. Playwright install: `pip install playwright && playwright install chromium`

Fix: Avoid this condition. Font paths: macOS `Menlo.ttc`. Linux: `DejaVuSansMono.ttf`. Windows: `consola.ttf`.

Fix: Avoid this condition. Stale state: Clean temp dirs before CLI demos (`rm -rf .foundry/`)

Fix: Use GIF.

Fix: Avoid this condition. `clarify` loop: call it at most twice per turn (style, then scene). Don't

Fix: Avoid this condition. `mono_green` / `mono_amber` force `color=0.0` (desaturate). If you override

Fix: Avoid this condition. Animation particle counts are tuned for ~640x480 canvases. On very large

Fix: Avoid this condition. Fractional `block` or `palette` will break quantization — keep them positive ints.

Fix: Avoid this condition. Very small sources (<100px wide) collapse under 8-10px blocks. Upscale the

Fix: Avoid this condition. Pallet keys are case-sensitive (`"NES"`, `"PICO_8"`, `"GAMEBOY_ORIGINAL"`).

Fix: Avoid this condition. Token references resolve by dotted path. `{colors.primary}` works;

Fix: Avoid this condition. `version: alpha` is the current spec version (as of Apr 2026). The spec

Fix: Avoid this condition. Section order is enforced. If the user gives you prose in a random order,

Fix: Avoid this condition. Negative dimensions need quotes too. `letterSpacing: -0.02em` parses as

Fix: Avoid this condition. Hex colors must be quoted strings. YAML will otherwise choke on `#` or

Fix: Don't nest component variants. `button-primary.hover` is wrong;

Fix: Do not claim browser verification unless it actually happened.

Fix: Do not produce generic SaaS layouts and call them designed.

Fix: Do not under-ask for high-fidelity work with no brand context.

Fix: Do not over-ask when the user already gave enough direction.

Fix: Do not strip the design doctrine while removing tool plumbing.

Fix: That creates drift.

Fix: They cause fake tool calls.

Fix: Avoid this condition. Strip secrets — scan source content for API keys, tokens, or credentials before writing any output f

Fix: The PNG is a review/regeneration aid; page prompts (written in Step 5) use the text descriptions in `characters/characters.md`, not the PNG. `image_generate` does not accept images as visual input

Fix: Avoid this condition. Steps 4/6 conditional - only if user requested in Step 2

Fix: Avoid this condition. Step 2 confirmation required - do not skip

Fix: Use stylized alternatives for sensitive public figures

Fix: Use absolute paths for `curl -o` — never rely on persistent-shell CWD across batches. Silent footgun: files land in the wrong directory and subsequent `ls` on the intended path shows nothing. See Step 7 "Download step".

Fix: Always download the URL returned by `image_generate` to a local PNG — downstream tooling (and the user's review) expects files in the output directory, not ephemeral URLs

Fix: Avoid this condition. Image generation: 10-30 seconds per page; auto-retry once on failure

Fix: Every spec URL, every protocol description, every "live" claim must be verified against the actual deployed site before the article goes public. Run `curl -s -o /dev/null -w "%{http_code}" <url>` for every linked page. If a spec returns 404, eith...

Fix: When describing Works With Agents protocols in public content, each layer must reference the existing standard that already serves that layer. Show where our protocols fit alongside, not instead of. Example: "Built above ...

Fix: Never include dead domain names (agenticflow.dev) or old branding (origami) in articles unless the article is specifically about a rebrand. These give life to dead things and confuse readers. "A domain that never resolved" beats naming a dead domain.

Fix: Avoid this condition. Wrong detail level for audience — Model names, quantization levels, parameter counts, and implementa

Fix: Avoid this condition. Wrong audience — These posts target technical leads and engineers, not executives or general public.

Fix: use real numbers from the project.

Fix: Avoid this condition. Too salesy → "Sign up for my course" kills credibility. Let the repo link do the work.

Fix: Avoid this condition. Too long → blog posts under 600 words. Postmortems 450-600. The audience wants technical depth, not

Fix: load it first.

Fix: "NHS Trust deployed on-prem agents and achieved 40% reduction" is fiction unless an NHS trust actually deployed it. Frame unvalidated outcomes as "Target Outcomes" or "What the methodology is designed to achieve."...

Fix: "We learned to communicate better" is worthless. "We now run quality-gate.py before every PyPI publish, which catches wrong install commands, dead URLs, and broken images" is valuable. Every lesson must name a concrete artifact (script, check, CI step, config file).

Fix: Never state a timeframe ("2 weeks", "3 days", "last month") without verifying from PyPI upload timestamps, git tags, or session logs. Check the actual release dates — `curl -s https://pypi.org/pypi/<pkg>/json` reveals upload timestamps. Frame unve...

Fix: not conflate them. The distinction matters for positioning — M365 dev is closer to Copilot extensions and agentic infrastructure than Po...

Fix: Do not scrape private profile data without explicit permission; if the user pastes profile text, use that as the source of truth.

Fix: Do not recommend huge portfolio projects when small targeted proof assets will work better.

Fix: Do not over-index on trend jargon without tying it back to their proven domain.

Fix: Do not make a senior person sound junior by saying they are “learning basics”.

Fix: Do not create a slow 6-month learning plan for someone who needs a job now.

Fix: Run the full verification suite (`references/verification-test-suite.md`): dispatch → sign → verify clean → tamper → unsigned. A 5-minute test catches byte-order bugs, API mismatches, and format drift before they hit production.

Fix: PyNaCl's `VerifyKey.verify()` expects the signed message bytes in the format `signature (64 bytes) || message`. If you concatenate in the wrong order (`message + signature`), verification always returns `BadSignatureError`. ...

Fix: Never include `_parent_seed` in subagent context. The 32-byte seed is the private key — leak it and an impostor can forge signatures as that agent. The parent keeps it locally; the subagent only gets `public_key`.

Fix: If a subagent's claims are modified after signing (e.g., `issues_found: 0` → `999`), the Ed25519 signature will not verify. This catches both accidental corruption and malicious modification.

Fix: Avoid this condition. Subagents often won't follow the output format on first dispatch — the `context_instruction` must be

Fix: Avoid this condition. Vercel deploy authorization failures show as FAIL but are maintainer-side — filter these in interpre

Fix: Avoid this condition. `gh pr checks` requires authenticated GitHub CLI. The script inherits the session's `gh` auth.

Fix: Avoid this condition. Subagents may embed the JSON manifest inside a markdown code fence — the extractor handles both bare

Fix: pass the public key from the dispatch output.

Fix: Avoid this condition. Signatures are 128 hex chars (64-byte Ed25519 signature), not 64 hex chars (SHA-256). If a manifest

Fix: ensure pynacl is installed in the active venv...

Fix: Avoid this condition. Enter may need to be pressed twice to submit in the TUI (once to finalize text, once to send).

Fix: Avoid sharing one working directory across parallel OpenCode sessions.

Fix: Avoid this condition. `process(action="log", session_id="<id>")`

Fix: Avoid this condition. If OpenCode appears stuck, inspect logs before killing:

Fix: Avoid this condition. PATH mismatch can select the wrong OpenCode binary/model config.

Fix: Ctrl+C to exit the TUI.

Fix: Avoid this condition. Interactive `opencode` (TUI) sessions require `pty=true`. The `opencode run` command does NOT need p

Fix: Avoid this condition. Run the `external-project-quality-sop` audit before pushing a project that carries the Works With Ag

Fix: Avoid this condition. `AGENTS.md` provides architecture overview for agent discoverability

Fix: Avoid this condition. `.gitignore` covers `.venv/`, `__pycache__/`, `.env`, `dist/`

Fix: Avoid this condition. `LICENSE` file exists (match what README claims — e.g., CC BY 4.0)

Fix: Avoid this condition. `delegate_task` for web research is unreliable with ALL models: Confirmed failures with both oMLX (A

Fix: Avoid this condition. `delegate_task` batch mode timeout with deepseek-v4-pro: When dispatching 2+ parallel subagent tasks

Fix: Keep context packs deterministic and small; bigger is not better if the worker loses the actual task.

Fix: Do not commit generated onboarding/session files unless they are intentional project files.

Fix: Avoid this condition. First-run agents may silently create workspace files; check `git status --short` after every real sm

Fix: Avoid this condition. A real CLI agent timeout may be caused by onboarding/profile setup, not by the wrapper.

Fix: Avoid this condition. Telegram/gateway messages may not expand CLI-only context references like `@file`; use tool calls or

Fix: Avoid this condition. `pause_instructions` are JSON — the cron agent must read them and call `cronjob action=pause`

Fix: Avoid this condition. Guard itself could fail — it has its own cron job with broad terminal access

Fix: Avoid this condition. Paused jobs must be manually resumed after fixing the root cause

Fix: Avoid this condition. Requires `agent_state_db` package on Python path

Fix: Avoid this condition. Only works if agents are registered in Agent State DB with their cron_job_id

Fix: Avoid this condition. CRITICAL: `CredentialStore().add(service, password='')` DELETES the credential. The `add()` method i

Fix: Avoid this condition. Protocol: JSON over socket — `{"action": "get", "service": "..."}` → `{"username": "...", "password"

Fix: Avoid this condition. Launcher `ensure_daemon()` needs `~/.hermes` on PYTHONPATH to import `credential_proxy.daemon`

Fix: Avoid this condition. Chrome CSV file should be deleted after import — it contains plaintext passwords.

Fix: with `chmod 600` after first write.

Fix: Avoid this condition. Chrome CSV has duplicate entries for same site — import handles this via upsert (493 rows → 424 atte

Fix: Avoid this condition. Master key file permissions: chmod 600. If lost, ALL passwords are unrecoverable.

Fix: Avoid this condition. Package dir MUST be `credential_proxy` (underscore), not `credential-proxy` — Python can't import hy

Fix: Avoid this condition. Daemon loads store once at startup — restart after importing new credentials

Fix: Avoid this condition. Only specific noise dirs are pruned (`node_modules`, `__pycache__`, `dist`, `lib`, `build`, `.foundr

Fix: Avoid this condition. `.git` directory is pruned but `.github/`, `.vscode/`, etc. are NOT — these contain CI workflows, se

Fix: ed to only prune NOISE_DIRS. CI configs and IDE settings now survive.

Fix: Avoid this condition. Priority scoring weights MD/docs heavily; adjust `get_file_priority()` for project-specific needs

Fix: Avoid this condition. Test files in test/ dirs are deprioritized but not excluded

Fix: output may slightly exceed max_chars (50K budget produced 55K output). Budget is checked per-section, not globally. For strict budgets, add a global counter that stops adding sections entirely when exceeded, rather than just truncating individual file previews.

Fix: use `eval $(...)` to capture. `scripts/cron_post_flight.py` takes `run_id status [summary]`.

Fix: Avoid this condition. The repo lives at `~/Agent-Projects/agent-state-db/`. If pip-installed, import directly: `from agent

Fix: NOT use `sys.path.insert(0, "~/.hermes/state")`.

Fix: Avoid this condition. SQLite `RETURNING` clause: fetch result BEFORE `conn.commit()` — the cursor stays open

Fix: Run `cleanup_stale_runs()` periodically.

Fix: Avoid this condition. `get_recent_failures()` counts CONSECUTIVE failures, not total

Fix: Avoid this condition. Locks auto-expire after TTL (default 300s)

Fix: Avoid this condition. `register_agent()` does upsert by name — same name returns existing agent_id

Fix: Avoid this condition. Gap > parity: When researching competitors, focus on what they DON'T do — that's where product oppor

Fix: `youtube-content` skill to extract transcripts, then analyze for gaps. See `agentic-methodology/references/agent-ecosystem-gaps.md` for example output.

Fix: direct research with web_search + terminal. Only use delegate_task for fire-and-forget long-running research where timing isn't critical.

Fix: ed: `return self.sign(payload) == signature_hex`. The bare function call was a NameError at runtime (only affects non-PyNaCl environments).

Fix: use `verify_with_public_key(public_key_hex, payload, sig)` — a stati...

Fix: Update all language implementations to match.

Fix: The TypeScript, Go, C#, Rust, and Shell vanilla agents still use the old L6 "task execution with tool simulation." Sync them to include the verification gate. The gate is opt-in (`verify_output=True`), so backward compat is preserved.

Fix: Fallback to local path if SDK not installed, but demo should work without SDK at all.

Fix: `crypto.randomUUID()` (built-in since Node 19+).

Fix: `fmt.Sprintf("%x", make([]byte, N))` for hex IDs.

Fix: Avoid this condition. Audit trail must be visible in demo output. Show `[completed]` and `[failed]` transactions.

Fix: The demo should show a `patient_identifiable` task being BLOCKED.

Fix: Avoid this condition. Class names must match across languages. `VanillaAgent`, `AgentIdentity`, `HandoffProtocol`, `Coordi

Fix: Don't require an API server. Vanilla agents work offline. No `workswithagents.dev` calls.

Fix: Don't depend on the SDK for vanilla agents. The whole point is zero external deps. Bundle the protocol classes into the file.

Fix: When creating a protocol example in the target project's `examples/` directory, wrap the target framework's import in `try/except ImportError` + set a `FRAMEWORK_AVAILABLE` flag. This lets the protocol demo layer run even when the fram...

Fix: add `--base master`. To check the default branch: `gh api repos/{owner...

Fix: The correct field for checking if a PR was merged is `mergedAt` (returns ISO timestamp or null). Using `merged` causes `gh` to print the full field list and output nothing useful. This wastes a full tool-call round-trip in cron mod...

Fix: always preferred for status checks. The user explicitly rejected subagent use fo...

Fix: When fixing silent exceptions, grep for the logging variable first: `grep -n 'self.logger\\|log = \\|getLogger' target_file.py`. Module-level `log = logging.getLogger(__name__)` is common; class methods use `self.logger` (often se...

Fix: Avoid this condition. CLA signing requires browser authentication — cannot be auto-signed from cron. cla-assistant.io has

Fix: run the three pre-flight checks (CLA → docs conventions → PR template) before creating a PR. Bot reviews (Greptile, CodeRabbit) catch the same issues — better to get them right on first push than to fix in a follow-up. A PR with bot...

Fix: After making changes but BEFORE pushing, run the same checks the target's CI will run. Find what CI does via `.github/workflows/` and replicate: `black --check <paths>`, `flake8 --extend-exclude=.venv <paths>`, `pytest`. For uv projects:...

Fix: When adding a new example/package to a monorepo that uses uv workspace with `members = [\"atomic-examples/*\"]`, every new package that depends on a workspace member MUST include `[tool.uv.sources]` pointing to the workspace. Missing...

Fix: `gh pr view --repo` and `gh issue view --repo` use GraphQL internally and can return "Could not resolve to a Repository" for repos with hyphens in specific positions (e.g., `molt-is-org/moltis` fails GraphQL but `gh api repos/molt...

Fix: use `curl -L` (follow redirects) when checking issue state: `curl -sL -H "Authorization: token $(gh auth token)" "https://api.github.com/repos/{owner}/{repo}/issues/{number}"`. ...

Fix: Writing `cat > /tmp/script.py << 'PYEOF'` with emoji characters (🟢, 🔴, ⚠️) in the heredoc body triggers a MEDIUM security block. This affects matrix-update scripts that need to replace emoji-decorated status lines. **W...

Fix: use `gh ... --jq '<filter>'` instead of piping to `python3 -c`. The `--jq` flag processes JSON output...

Fix: When you `gh repo fork` and push to a personal fork, `gh pr create` from the clone directory will fail with \"you must first push the current branch to a remote.\" Use `gh pr create --repo {owner}/{repo} --head {your-username}:{branch-name} --body-fi...

Fix: The npm org (`@workswithagents`) must exist on npmjs.com. The token in `~/.npmrc` must have publish permissions on the org. If `npm publish` fails with 404 on the org, check: org exists? token fresh? token has publish access? Use `credential-proxy get "np...

Fix: spec URLs that 404 because content wasn't deployed to the VPS, filenames changed but issue bodies weren't updated, or packages weren't published. After raising ANY issue or comment with links, run the verification step above. Bro...

Fix: log the full URL in the integration log.

Fix: this to check issue...

Fix: Avoid this condition. `gh issue comment` syntax is NOT `gh issue comment {owner}/{repo} {number}`. The correct form is `gh

Fix: When `gh issue create --body` contains code with backticks, single quotes, or special characters, write the body to a temp file first, then use `--body-file`. Python's `tempfile.NamedTemporaryFile` is the cleanest approach for programmatic issue creation.

Fix: include a code snippet.

Fix: Avoid this condition. CC BY 4.0 is permissive enough. Lead with the license in proposals.

Fix: Every touchpoint goes in the integration log. The matrix gets updated.

Fix: Don't propose multiple protocols at once. Pick the ONE protocol that best fits their stated gap.

Fix: Don't spam. One well-researched issue per project. Wait for response before second touch.

Fix: Don't make the proposal about us. Frame it as solving THEIR problem.

Fix: Don't propose solutions to problems they don't have. Search their issues first. Cite their own words.

Fix: Check `archived: true` before investing time.

Fix: Avoid this condition. Patch tool with `replace_all=true` on short patterns can merge lines. When the old_string is somethi