gentle-ai-issue-creation

Create Gentle AI issues with issue-first checks. Trigger: creating GitHub issues, bug reports, or feature requests.

Quality

79%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/issue-creation/SKILL.md

Gentle AI — Issue Creation Skill

When to Use

Load this skill whenever you need to:

Report a bug in gga
Request a new feature or enhancement
Open any GitHub issue on the Gentleman-Programming/gentle-ai repository

Critical Rules

Blank issues are DISABLED — blank_issues_enabled: false in .github/ISSUE_TEMPLATE/config.yml. You MUST use a template.
status:needs-review is applied automatically — every new issue gets this label; you do NOT add it manually.
status:approved is REQUIRED before ANY work begins — a maintainer must label the issue before you or anyone opens a PR.
Questions go to Discussions — use GitHub Discussions, NOT issues, for questions and general conversation.
No Co-Authored-By trailers — never add AI attribution to commits.

Workflow

1. Search existing issues → confirm it's not a duplicate
   https://github.com/Gentleman-Programming/gentle-ai/issues

2. Choose the correct template:
   - Bug   → .github/ISSUE_TEMPLATE/bug_report.yml
   - Feat  → .github/ISSUE_TEMPLATE/feature_request.yml

3. Submit the issue → status:needs-review is applied automatically

4. Wait — a maintainer reviews and adds status:approved (or closes)

5. Only AFTER status:approved → open a PR referencing this issue

⚠️ STOP after step 3. Do NOT open a PR until the issue has status:approved.

Bug Report

Template path: .github/ISSUE_TEMPLATE/bug_report.yml Auto-labels: bug, status:needs-review

Required Fields

Field	Description
Pre-flight Checklist	Confirm no duplicate exists; confirm PR-approval understanding
Bug Description	Clear description of what the bug is
Steps to Reproduce	Numbered steps to reproduce the behavior
Expected Behavior	What should happen
Actual Behavior	What actually happens
Gentle AI Version	Output of `gga version`
Operating System	macOS / Linux distro / Windows / WSL
AI Agent / Client	Claude Code / OpenCode / Gemini CLI / Cursor / Windsurf / Other
Affected Area	See area list below

Affected Areas

CLI (commands, flags) · TUI (terminal UI) · Installation Pipeline · Agent Detection · System Detection · Catalog/Steps · Documentation · Other

Example CLI Command

gh issue create \
  --repo Gentleman-Programming/gentle-ai \
  --template bug_report.yml \
  --title "fix(agent): Claude Code not detected on Linux Arch"

Or open the web form directly:

https://github.com/Gentleman-Programming/gentle-ai/issues/new?template=bug_report.yml

Feature Request

Template path: .github/ISSUE_TEMPLATE/feature_request.yml Auto-labels: enhancement, status:needs-review

Required Fields

Field	Description
Pre-flight Checklist	Confirm no duplicate exists; confirm PR-approval understanding
Affected Area	Which area of `gga` this feature affects
Problem Statement	Describe the problem this feature solves
Proposed Solution	Specific description — include example `gga` command/output if relevant
Alternatives Considered	(optional) Other approaches you thought about
Additional Context	(optional) Screenshots, config files, etc.

Example CLI Command

gh issue create \
  --repo Gentleman-Programming/gentle-ai \
  --template feature_request.yml \
  --title "feat(tui): add keyboard shortcut help overlay"

Or open the web form directly:

https://github.com/Gentleman-Programming/gentle-ai/issues/new?template=feature_request.yml

Label System

Status Labels (applied to Issues)

Label	Description	Who Applies
`status:needs-review`	Newly opened, awaiting maintainer review	Auto (template)
`status:approved`	Approved — work can begin	Maintainer only
`status:in-progress`	Being actively worked on	Contributor
`status:blocked`	Blocked by another issue or external dependency	Maintainer / Contributor
`status:wont-fix`	Out of scope or won't be addressed	Maintainer only

Type Labels (applied to Issues and PRs)

Label	Description
`bug`	Defect report
`enhancement`	Feature or improvement request
`type:bug`	Bug fix (used on PRs)
`type:feature`	New feature (used on PRs)
`type:docs`	Documentation only (used on PRs)
`type:refactor`	Refactoring, no functional changes (used on PRs)
`type:chore`	Build, CI, tooling (used on PRs)
`type:breaking-change`	Breaking change (used on PRs)

Priority Labels

Label	Description
`priority:critical`	Blocking issues, security vulnerabilities
`priority:high`	Important, affects many users
`priority:medium`	Normal priority
`priority:low`	Nice to have

Maintainer Approval Workflow

Issue submitted
      │
      ▼
status:needs-review  ← auto-applied by template
      │
      ▼
Maintainer reviews
      │
  ┌───┴────────────────┐
  │                    │
  ▼                    ▼
status:approved    Closed
(work can begin)   (invalid / duplicate / wont-fix)
      │
      ▼
Contributor comments "I'll work on this"
      │
      ▼
status:in-progress
      │
      ▼
PR opened with `Closes #<N>`

Decision Tree

Do you have a question or idea to discuss?
├── YES → GitHub Discussions (NOT issues)
│         https://github.com/Gentleman-Programming/gentle-ai/discussions
└── NO  → Is it a defect in gga?
          ├── YES → Bug Report template
          └── NO  → Feature Request template
                    │
                    ▼
          Does a similar issue already exist?
          ├── YES → Comment on existing issue instead
          └── NO  → Submit new issue → wait for status:approved

Commands

Search for Existing Issues

# Search open issues
gh issue list --repo Gentleman-Programming/gentle-ai --state open --search "your keywords"

# Search all issues including closed
gh issue list --repo Gentleman-Programming/gentle-ai --state all --search "your keywords"

Create a Bug Report

gh issue create \
  --repo Gentleman-Programming/gentle-ai \
  --template bug_report.yml \
  --title "fix(<scope>): <short description>"

Create a Feature Request

gh issue create \
  --repo Gentleman-Programming/gentle-ai \
  --template feature_request.yml \
  --title "feat(<scope>): <short description>"

Check Issue Status

gh issue view <number> --repo Gentleman-Programming/gentle-ai

Valid Scopes for Issue Titles

tui, cli, installer, catalog, system, agent, e2e, ci, docs

Repository: sergiodvillegas-art/gentle-ai
Commit: 3bfa934

Last updated: 6 days ago
Created: 6 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.