gotcha

Maintain a living log of project pitfalls in GOTCHAS.md.

Updated Apr 18, 2026
One-click install
npx skills add https://github.com/exerias21/brainstorm-toolkit --skill gotcha-exerias21
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: gotcha
Source: https://github.com/exerias21/brainstorm-toolkit/tree/main/skills/gotcha
Command: npx skills add https://github.com/exerias21/brainstorm-toolkit --skill gotcha-exerias21

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill maintains a living log of project-specific pitfalls—non-obvious traps, hard-won lessons, and best-practice reminders—to prevent repeating mistakes.

Core Features & Use Cases

  • Read and display the current gotcha list organized by category, with counts per category.
  • Add a new entry via /gotcha by providing category, title, description, Why, and Fix; automatically updates or creates GOTCHAS.md.
  • Update existing entries to avoid duplicates and keep the log current; supports a default category structure if the file is missing.

Quick Start

Invoke /gotcha <text> to add a new gotcha entry to the gotchas file.

Frequently Asked Questions about gotcha

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I log project pitfalls and code review lessons in a markdown file?

You can log project pitfalls by invoking a command to add entries with category, title, description, why, and fix fields, which automatically creates or updates a GOTCHAS.md file to prevent repeating mistakes.

What is a gotcha log and how does it help with knowledge management onboarding?

A gotcha log is a living record of non-obvious traps and hard-won lessons that centralizes project knowledge to prevent repeated mistakes during codebase onboarding and reviews.

Can I organize captured codebase pitfalls by category and see counts per category?

Yes, the system reads and displays the current gotcha list organized by category, including counts per category, and initializes a default category structure if the log file is missing.

Does the gotcha log support updating existing pitfalls to avoid duplicate entries?

Yes, it supports updating existing entries to avoid duplicates and keep the log current, automatically merging new information into the existing markdown file structure.

What's the best way to maintain a living log of hard-won lessons for a development team?

Maintain a living log of hard-won lessons by centralizing project pitfalls into a configurable markdown file, applying it to codebases and onboarding workflows where known traps are revisited.