issue-filing

Filing Issues

Location: patterns/$GITHUB_USER/issues/ for framework issues or pattern architecture questions

IMPORTANT: File issues ONLY after exhausting all other approaches AND getting user permission.

Prerequisites before filing:

1. ✅ Checked official ~/Code/labs/docs/common/ documentation
2. ✅ Searched community-docs superstitions
3. ✅ Studied similar working patterns
4. ✅ Tried multiple different approaches (document all attempts)
5. ✅ Asked user if they want you to file an issue

Never file an issue without explicit user permission!

When to File an Issue

After above prerequisites:

• Encountering framework behavior you don't understand
• Pattern architecture questions that aren't answered by docs
• Suspected framework bugs or limitations
• Questions about "correct" way to do something
• Edge cases that might help others

File naming: ISSUE-Brief-Title.md

Example: ISSUE-Automatic-Side-Effects.md, ISSUE-Reactive-Computed-Timing.md

Issue Template

# Issue: [Brief Question/Problem Title]

## Summary

1-2 sentence summary of the issue or question.

## Use Case

**Pattern:** Name of the pattern where this came up

**What you're trying to accomplish:**
- Clear description of the goal
- Why you need this behavior
- Context about the pattern

## Current State (What Works)

Show what you have working currently (if anything):

```typescript
// Code that works (even if not ideal)

What We Tried (Failed Attempts)

Attempt 1: [Approach Name]

// Code that didn't work

Error:

Exact error message

Analysis: Why you think this didn't work

Attempt 2: [Another Approach]

[Same structure]

Questions

1. Main question about correct approach?
2. Alternative approaches to consider?
3. Is this even possible in current framework?
4. Missing something obvious?

Desired Behavior

What you want to happen:

1. Step 1
2. Step 2
3. Expected outcome

Environment

• CommonTools framework (latest version)
• Any relevant pattern features being used
• Related patterns or components

Any guidance on the correct approach would be greatly appreciated!

## When to File vs. When to Use Community Docs

**File an issue when:**
- ✅ You have a specific, complex problem
- ✅ You've tried multiple approaches
- ✅ You have code examples showing what didn't work
- ✅ It's a framework design or architecture question
- ✅ It might be a framework bug or limitation
- ✅ You want framework author feedback

**Use community-docs/superstitions when:**
- ✅ You discovered a simple pattern that works
- ✅ It's a one-line fix or small code pattern
- ✅ You want to share empirical knowledge
- ✅ It might help others encountering similar issues
- ✅ You're not sure if it's the "right" way

**Examples:**

**Issue:** "How do I automatically trigger side effects when reactive values change?" (complex architecture question, multiple failed attempts)

**Superstition:** "Use `Cell<Item[]>` not `Cell<OpaqueRef<Item>[]>` in handler signatures" (simple pattern that works)

## Workflow

**CRITICAL: Issues are a last resort. Only create after exhausting all other options.**

1. **Encounter framework confusion** that docs don't resolve
2. **Exhaust recovery strategies:**
   - Check official labs/docs/
   - Search community-docs superstitions
   - Study similar working patterns
   - Try multiple different approaches
   - Consider asking user for clarification first
3. **Ask user permission:**

"I've tried [list approaches]. This seems like a framework architecture question. Would you like me to file an issue in patterns/$GITHUB_USER/issues/ to document this for framework authors to review?"

4. **Only if user says yes:**
- Check if similar issue exists in your issues/ folder
- Create new issue file with template
- Include all failed attempts with code
- Document clear problem statement
- Commit: `"Add issue: [brief description]"`

**Never file an issue proactively - always get user approval first.**

**Issues are questions for framework authors, not empirical discoveries.**

## Related Skills

- **recovery-strategies** - Use issue filing as final escalation step
- **community-docs** - Check before filing issues
- **pattern-development** - Issues arise during development