community-docs

jkomoros's avatarfrom jkomoros

Community superstitions - unverified observations from pattern development. Use when encountering undocumented edge cases or framework quirks not in official docs. Verified knowledge should be upstreamed to labs docs.

⭐6stars🔀8forks📁View on GitHub🕐Updated Dec 30, 2025
[Knowledge Base]

When & Why to Use This Skill

The Community Docs (Superstitions) skill is a specialized knowledge management tool designed for developers and AI agents to navigate undocumented framework quirks and edge cases. It provides a structured repository for 'superstitions'—empirical, unverified observations discovered during development—offering a critical safety net when official documentation is insufficient. By bridging the gap between experimental fixes and official docs, it enhances debugging efficiency and promotes a workflow for upstreaming verified knowledge.

Use Cases

  • Troubleshooting undocumented edge cases: Accessing a community-driven repository to find experimental solutions for framework behaviors not covered in official manuals.
  • Resolving complex TypeScript and reactivity errors: Searching through empirical observations to identify potential fixes for niche coding issues and unexpected framework quirks.
  • Managing developer tribal knowledge: Documenting new 'superstitions' discovered during pattern development and tracking them until they can be verified and upstreamed.
  • Advanced AI agent recovery: Providing Claude with a secondary knowledge source to consult when standard documentation fails to resolve implementation bottlenecks.
namecommunity-docs
description>

Community Docs (Superstitions)

Location: community-docs/ in community-patterns repo

CRITICAL: These are NOT official framework documentation. Always check ~/Code/labs/docs/common/ first.

Community docs capture empirical observations discovered during pattern development - unverified things that seemed to work but may be coincidence or context-specific.

Superstitions (⚠️ Treat With Skepticism)

Location: superstitions/

Single observations only. May be wrong, incomplete, or context-specific.

  • Treat with extreme skepticism
  • May be wrong, incomplete, or context-specific
  • Each has prominent warning disclaimer
  • Try if completely stuck, but verify thoroughly

When to Consult Superstitions

After checking official labs/docs/ first:

  • Encountering undocumented edge cases
  • Framework behaving unexpectedly
  • TypeScript errors not explained in official docs
  • Before creating new superstition (check if already documented)

Do NOT consult before official docs - labs/docs/ is always more authoritative!

Searching Superstitions

# Search superstitions
grep -r "Cell.*handler" community-docs/superstitions/

# List superstitions by topic
ls community-docs/superstitions/ | grep "types-"
ls community-docs/superstitions/ | grep "reactivity-"

If a Superstition Works

Upstream it to labs docs instead of keeping it here:

  1. Identify the appropriate doc in ~/Code/labs/docs/common/
  2. Add the information to that doc
  3. Create a PR to labs
  4. Once merged, delete the superstition

The goal is for verified knowledge to live in official docs, not here.

Creating a New Superstition

Only after solving something not in any docs:

  1. Search first - Check it's not already documented:

    grep -r "your topic" ~/Code/labs/docs/common/
grep -r "your topic" community-docs/superstitions/

  2. Create file: community-docs/superstitions/YYYY-MM-DD-topic-brief-description.md

    • Use topic prefixes: types-, reactivity-, jsx-, handlers-, llm-, patterns-, etc.

  3. Copy template from community-docs/superstitions/README.md

  4. Include full ⚠️ disclaimer at top

  5. Document:

    • What problem you had
    • What you tried that didn't work
    • What solution seemed to work
    • Code examples (before/after)
    • Your context
    • Related official docs

  6. Commit: "Add superstition: [brief description]"

Remember: You're creating a hypothesis, not stating fact! Be humble about uncertainty.

Deprecated Tiers

The blessed/ and folk_wisdom/ directories are deprecated. Previously we had a three-tier promotion system. Now, verified knowledge should be upstreamed directly to labs docs.

Important Notes

Skepticism is critical:

  • Superstitions may be wrong or context-specific
  • Always prefer official labs/docs/ when they exist

Do NOT:

  • Trust superstitions blindly
  • Skip checking official docs first
  • Create superstition for things in official docs

DO:

  • Read disclaimer on every superstition
  • Verify against official docs
  • Test thoroughly before relying on it
  • Upstream verified knowledge to labs docs

Superstitions are a safety net for edge cases, not a primary reference!

  • recovery-strategies - Use superstitions as part of recovery escalation
  • pattern-dev - Reference when stuck on implementation