176 lines
5.0 KiB
Markdown
176 lines
5.0 KiB
Markdown
---
|
|
name: stack-feedback
|
|
version: 0.3.0
|
|
description: Creates GitHub issues for problems discovered while using @outfitter/* packages. Use when finding bugs, missing features, unclear documentation, or improvement opportunities.
|
|
context: fork
|
|
agent: stacker
|
|
allowed-tools: Bash(gh *) Bash(bun *) Read
|
|
user-invocable: false
|
|
---
|
|
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```markdown
|
|
## Stack Feedback
|
|
|
|
- [ ] #123: Result.unwrap throws on valid input — bug
|
|
```
|
|
|
|
## Check Existing Issues
|
|
|
|
Before creating a new issue, check if it already exists:
|
|
|
|
```bash
|
|
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](references/migration-feedback.md)
|