| description | File feedback, goals, feature requests, integration requests, rough DX notes, and bugs against any recallnet repo with GitHub CLI. Use this skill proactively whenever work reveals reusable package gaps, template/tooling gaps, API friction, missing integrations, unclear docs, or legitimate bugs. Do not wait until the end of the session; file the issue while working. |
| metadata | {"github-path":"skills/issue-filing","github-ref":"refs/tags/v1.1.0","github-repo":"https://github.com/recallnet/recall-skills","github-tree-sha":"60c58613b0ea20bb906111e15067abcc22379557"} |
| name | issue-filing |
Issue Filing
Use this skill whenever work uncovers feedback that belongs in a recallnet repo.
Determine Target Repo
Choose the target repo from context:
recallnet/tradecore — when the finding is about:
- TradeCore package gaps, missing reusable abstractions, or integrations
- Venue bugs, integration constraints, denomination rules in
@recallnet/* packages
- API friction, confusing docs, or awkward ergonomics in TradeCore packages
- Legitimate bugs with clear repro in TradeCore behavior
recallnet/skunkworks-template — when the finding is about:
- Gaps in
AGENTS.md or CLAUDE.md guidance
- Pre-commit hooks, QA scripts, or quality gate improvements
- Skill policy, skills-lock.json, or template structure
- Docs governance, docs/INDEX.md, or template scaffolding
Other repos — use gh issue create --repo <owner>/<repo> with Goal or Bug template as appropriate.
What Belongs Here vs a Learnings Entry
Use issue-filing for findings with a concrete, actionable target (a specific repo that should change).
Write to learnings/TRADE-LEARNINGS.md or learnings/AGENT-LEARNINGS.md for cross-repo patterns, meta insights, or findings where the right action isn't a single repo change.
Timing
File the issue while working. Do not defer until the task is over.
If you need to unblock quickly with a local workaround, do that — but still log the issue immediately so the simplification path is recorded.
Choose the Right Issue Type
Use the Goal template for:
- New capabilities, integrations, or reusable abstractions
- Package requests and feature requests
- Most DX improvements
Use the Bug template for:
- Broken behavior with clear repro
- Incorrect results or missing expected behavior
- Regressions or critical DX failures
When in doubt, prefer Goal unless the report is clearly about something broken.
CLI
gh issue create --repo recallnet/tradecore --template Goal --title "Goal: <short outcome>" --body-file <file>
gh issue create --repo recallnet/tradecore --template Bug --title "Bug: <short summary>" --body-file <file>
gh issue create --repo recallnet/skunkworks-template --template Goal --title "Goal: <short outcome>" --body-file <file>
gh issue create --repo recallnet/skunkworks-template --template Bug --title "Bug: <short summary>" --body-file <file>
Goal Issue Format
## Goal
Ship X so that Y.
## Success Criteria
- [ ] ...
- [ ] ...
## Scope (In)
- ...
## Scope (Out)
- ...
## Constraints
- ...
## Dependencies / Blockers
- ...
## Risks
- ...
## References
- skunkworks branch / commit / file links
- related issues or docs
## Notes
...
Bug Issue Format
## Summary
When X happens, Y fails.
## Steps to Reproduce
1. ...
2. ...
## Expected Behavior
Expected ...
## Actual Behavior
Actual ...
## Impact / Severity
High/medium/low with user or executor impact.
## Environment
- Commit/Version: ...
- Runtime: ...
- OS: ...
## Logs / Screenshots
...
Filing Standard
- Be concrete and concise
- Tie the request to reusable value, not just a local workaround
- Include enough context for a maintainer to act without re-discovery
- Include skunkworks references when they help
- Return the created issue URL after filing
While Working
If the current task reveals an improvement opportunity, file it proactively.
Examples:
- You need a reusable client, parser, integration, or helper that belongs in TradeCore
- You hit awkward package ergonomics or confusing setup
- You implement something locally that should later migrate into a shared package
- You find broken behavior in a TradeCore package or repo workflow
- You notice a gap in skunkworks-template AGENTS.md, hooks, or QA gates
Do not treat "we can hack around it locally" as a reason not to file the issue.
