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:

   bash

   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!

Related Skills

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