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

1. Blank issues are DISABLED — blank_issues_enabled: false in .github/ISSUE_TEMPLATE/config.yml. You MUST use a template.
2. status:needs-review is applied automatically — every new issue gets this label; you do NOT add it manually.
3. status:approved is REQUIRED before ANY work begins — a maintainer must label the issue before you or anyone opens a PR.
4. Questions go to Discussions — use GitHub Discussions, NOT issues, for questions and general conversation.
5. 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