gentle-ai-issue-creation

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.
Pre-submission privacy review is MANDATORY — before gh issue create, replace private project names, usernames, home paths, hostnames, secrets/credentials, and environment-specific identifiers with explicit placeholders (<project-name>, <user>, <hostname>, <token>). Keep reproduction structure with placeholders — never redact an example into nothingness. Do NOT redact intentionally public identifiers like gentle-ai, engram, go. A final body scan happens immediately before publish.

Pre-submission Privacy Review

Every issue body is scanned immediately before gh issue create. The scan replaces — never deletes — environment-specific data with explicit placeholders so the reproduction still teaches:

Category	Replace with	Example (before → after)
Private project names	`<project-name>`	`my-private-project-b` → `<project-name>`
Usernames	`<user>`	`C:\Users\my-real-username\go\bin` → `C:\Users\<user>\go\bin`
Hostnames	`<hostname>`	`devbox-macbook.local` → `<hostname>`
Home paths	`/home/<user>` or `C:\Users\<user>`	(covered above)
API keys, tokens, passwords	`<token>` / `<password>`	`ghp_abc123...` → `<token>`
Internal ports / hostnames	`<host>:<port>`	`10.0.0.42:5432` → `<host>:<port>`

Intentionally public identifiers are NOT redacted: tool names (gentle-ai, engram, go, node, python), package names, public documentation URLs, generic example domains (example.com, localhost).

Rule of thumb: if the reader can run the reproduction step after you replace every identifier with its placeholder, the sanitization is correct. If a step becomes impossible (because the placeholder consumed a needed value), that step needs the value — and you should mark it <value-required> and explain in the body what the user should fill in.

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

About this skill

When to Use

Critical Rules

Pre-submission Privacy Review

Workflow

Bug Report

Required Fields

Affected Areas

Example CLI Command

Feature Request

Required Fields

Example CLI Command

Label System

Status Labels (applied to Issues)

Type Labels (applied to Issues and PRs)

Priority Labels

Maintainer Approval Workflow

Decision Tree

Commands

Search for Existing Issues

Create a Bug Report

Create a Feature Request

Check Issue Status

Valid Scopes for Issue Titles