issue-filing

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.