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

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.
6. 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:

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

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

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)

Type Labels (applied to Issues and PRs)

Priority Labels

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