community-docs

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!

Related Skills

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