tomevault-io 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:
- Review all feedback items
- Deduplicate similar issues
- Create issues with cross-references where related
- Update tracking with issue numbers
Best Practices
- Be specific — Include package, function, and line if known
- Provide context — Explain what task led to discovery
- Include workaround — If you found one, share it
- Link related issues — Reference if similar issues exist
- Stay constructive — Focus on improvement, not complaint
References
- Migration-specific feedback
Converted and distributed by TomeVault — claim your Tome and manage your conversions.