Gotchas Library

The Gotchas library is a curated collection of pitfalls, workarounds, and "things that will bite you" — organized by technology and filtered to each project's stack. Agents consult it during planning and code review to avoid known traps.

What Are Gotchas?

Documented, real-world problems tied to specific technologies:

  • Common mistakes and their fixes
  • Undocumented or surprising behavior
  • Version-specific breaking changes
  • Configuration traps
  • Performance pitfalls

Gotchas are stored as gotchas-type books in the same vault system as project knowledge. They're one of only two book types (knowledge / gotchas).

Structure

Trinity seeds three gotcha books out of the box — they're shared across projects (no project_id), so the pool compounds as more users and agents contribute:

Languages

Pitfalls specific to programming languages. Seeded sections:

  • TypeScript — type narrowing edge cases, declaration merging, etc.
  • Python — mutable defaults, import cycles, etc.
  • SQL — join semantics, NULL handling, locking behavior, etc.

Frameworks

Framework-specific issues. Seeded sections:

  • React — stale closures, effect dependencies, rendering order
  • Next.js — server/client boundary, caching behavior, routing

Tools

Tooling + infrastructure gotchas. Seeded sections:

  • SQLite — concurrency, transaction modes
  • Git — general + a dedicated worktrees chapter for parallel execution gotchas
  • Claude — general + a dedicated claude-code chapter
  • npm — registry / lockfile quirks
  • Docker — Compose + container footguns

Each section has chapters (general, plus topic-specific ones like worktrees or claude-code), and each chapter holds pages with the individual gotcha entries.

How Gotchas Accumulate

From Execution

The Documenter phase (story pipeline) and the checkpoint documentation phase record gotchas discovered during implementation. These are real, encountered-in-the-wild entries — not speculation. Writes go through the write_gotcha MCP tool, which normalizes and dedupes by slug: if an entry with the same slug exists, it's updated in place instead of duplicated.

From Audits

The Audit feature flags patterns that match known gotchas (or that should become new gotchas). When it does, those get added through the same path.

How Agents Use Gotchas

During Analyst and Auditor phases, agents query gotchas filtered to the project's stack:

  • MCP tool: get_vault_index surfaces gotchas alongside regular knowledge
  • Stack-aware filtering: stack-match.ts matches a project's stack_items against gotcha book/section slugs so only relevant ones are surfaced
  • Each phase incorporates relevant gotchas into its plan or review checklist

The trinity-app-vault skill (scaffolded into each project's .claude/skills/) wraps these tools and gives agents how-to guidance for consulting the library.

Viewing Gotchas

Two entry points:

  • Gotchas sidebar item in the Hub section — goes straight to the first available book/section/chapter/page, deep-linkable via /gotchas/{book}/{section}/{chapter}/{page}
  • From inside Knowledge — browse the gotchas books alongside your project book

Each gotcha page typically includes:

  • Title — short summary of the issue
  • Problem — what goes wrong and when
  • Example — code demonstrating the trap
  • Fix — how to avoid or resolve it
  • Context — versions / configurations where this applies

Gotchas vs. Knowledge Base

Gotchas (book type gotchas) Knowledge Base (book type knowledge)
Technology-specific pitfalls Project-specific documentation
Shared across projects (no project_id) by default, filtered to each project's stack Scoped to one project via project_id
Accumulated from execution + audits, deduped by slug Built during onboarding, import, and execution
Read-mostly (agents consult them) Read-write (agents update frequently)

Both live in the same knowledge_books / knowledge_chapters / knowledge_pages tables — the book_type column is what distinguishes them.

Contributing Gotchas Manually

Agents do most of the writing, but you can also add entries by hand:

  1. Open the relevant gotchas book from the sidebar
  2. Navigate to (or create) the appropriate section + chapter
  3. Add a new page

Format entries clearly — agents read them as-is, so structure matters:

# Short descriptive title
 
## Problem
 
What goes wrong and when.
 
## Example
 
Code showing the issue.
 
## Fix
 
How to avoid or resolve it.
 
## Context
 
Versions, frameworks, or configurations this applies to.

The write_gotcha MCP tool normalizes agent writes, but manual entries follow the same shape.