Stack Feedback

Create GitHub issues on outfitter-dev/outfitter for problems discovered while using the stack.

When to Use

Invoke this skill when you discover:

• Bugs in @outfitter/* packages
• Missing features that would improve DX
• Unclear documentation that caused confusion
• Pattern gaps where guidance is missing
• Ergonomic issues that made tasks harder than expected

Issue Categories

Category	Label	Example
bug	bug	Package throws when it should return Result
enhancement	feature	Add helper for common pattern
docs	documentation	Handler contract docs missing edge case
unclear-pattern	question	How to handle X scenario with Result types
dx	dx	Error message unclear, hard to debug
migration-pattern	adoption	Migration scenario lacks guidance
conversion-helper	adoption	Need utility for legacy conversion
compatibility	adoption	Breaking change concern
migration-docs	migration, documentation	Migration docs gap

Using the Helper Script

The preferred method for creating issues. The script handles templates, labels, and validation.

Basic Usage

bun plugins/outfitter-stack/skills/stack-feedback/scripts/create-issue.ts \
  --type bug \
  --title "Result.unwrap throws on valid input" \
  --package "@outfitter/contracts" \
  --description "When calling unwrap on Ok value, it unexpectedly throws" \
  --actual "Throws TypeError instead of returning value"

Dry-Run Mode (Default)

By default, the script outputs JSON with the gh command without executing it:

{
  "command": "gh issue create --repo outfitter-dev/outfitter --title '[Bug] Result.unwrap throws...' --label bug --label feedback --label source/agent --body '...'",
  "title": "[Bug] Result.unwrap throws on valid input",
  "labels": ["bug", "feedback", "source/agent"],
  "body": "## Package\n\n`@outfitter/contracts`\n..."
}

Origin Detection

The script automatically detects the git origin of the current directory and adds a "Discovered In" section to the issue body with a link to the source repo. This helps track where feedback originates.

Submit Mode

Add --submit to actually create the issue:

bun plugins/outfitter-stack/skills/stack-feedback/scripts/create-issue.ts \
  --type enhancement \
  --title "Add Result.tap helper" \
  --package "@outfitter/contracts" \
  --description "Helper to run side effects without unwrapping" \
  --useCase "Logging without breaking method chains" \
  --submit

View Template Requirements

Run with just --type to see required and optional fields:

bun plugins/outfitter-stack/skills/stack-feedback/scripts/create-issue.ts --type bug

Available Types

Type	Required Fields
bug	package, description, actual
enhancement	package, description, useCase
docs	package, description, gap
unclear-pattern	package, description, context
dx	package, description, current
migration-pattern	sourcePattern, description, scenario
conversion-helper	legacyPattern, description, targetPattern
compatibility	package, description, breakingChange
migration-docs	area, description, gap

Manual Issue Creation

For cases where the script doesn't fit, use gh directly:

gh issue create \
  --repo outfitter-dev/outfitter \
  --title "[Bug] Brief description" \
  --label "bug" \
  --label "feedback" \
  --label "source/agent" \
  --body "$(cat <<'EOF'
## Package

`@outfitter/package-name`

## Description

What went wrong or what's missing.

## Actual Behavior

What actually happens.

---

*Created via `outfitter-stack:stack-feedback` skill*
EOF
)"

Tracking Feedback

After creating, track in your project:

## Stack Feedback

- [ ] #123: Result.unwrap throws on valid input — bug

Check Existing Issues

Before creating a new issue, check if it already exists:

gh issue list --repo outfitter-dev/outfitter --label feedback
gh issue list --repo outfitter-dev/outfitter --search "{{KEYWORDS}}"

Batch Feedback

If multiple issues have accumulated:

1. Review all feedback items
2. Deduplicate similar issues
3. Create issues with cross-references where related
4. Update tracking with issue numbers

Best Practices

1. Be specific — Include package, function, and line if known
2. Provide context — Explain what task led to discovery
3. Include workaround — If you found one, share it
4. Link related issues — Reference if similar issues exist
5. Stay constructive — Focus on improvement, not complaint

References

• Migration-specific feedback