OpenParable
Skip to content
← Back to skills

Gentle AI Issue Creation

Productivity
gentle-ai-issue-creation

Gentle AI Issue Creation is an Agent Skill for productivity published in the Gentleman-Programming/gentle-ai repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Gentleman-Programming/gentle-ai/blob/HEAD/skills/issue-creation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/gentle-ai-issue-creation, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Gentle AI — Issue Creation Skill

When to Use

Load this skill whenever you need to:

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

FieldDescription
Pre-flight ChecklistConfirm no duplicate exists; confirm PR-approval understanding
Bug DescriptionClear description of what the bug is
Steps to ReproduceNumbered steps to reproduce the behavior
Expected BehaviorWhat should happen
Actual BehaviorWhat actually happens
Gentle AI VersionOutput of gga version
Operating SystemmacOS / Linux distro / Windows / WSL
AI Agent / ClientClaude Code / OpenCode / Gemini CLI / Cursor / Windsurf / Other
Affected AreaSee 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

FieldDescription
Pre-flight ChecklistConfirm no duplicate exists; confirm PR-approval understanding
Affected AreaWhich area of gga this feature affects
Problem StatementDescribe the problem this feature solves
Proposed SolutionSpecific 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)

LabelDescriptionWho Applies
status:needs-reviewNewly opened, awaiting maintainer reviewAuto (template)
status:approvedApproved — work can beginMaintainer only
status:in-progressBeing actively worked onContributor
status:blockedBlocked by another issue or external dependencyMaintainer / Contributor
status:wont-fixOut of scope or won't be addressedMaintainer only

Type Labels (applied to Issues and PRs)

LabelDescription
bugDefect report
enhancementFeature or improvement request
type:bugBug fix (used on PRs)
type:featureNew feature (used on PRs)
type:docsDocumentation only (used on PRs)
type:refactorRefactoring, no functional changes (used on PRs)
type:choreBuild, CI, tooling (used on PRs)
type:breaking-changeBreaking change (used on PRs)

Priority Labels

LabelDescription
priority:criticalBlocking issues, security vulnerabilities
priority:highImportant, affects many users
priority:mediumNormal priority
priority:lowNice 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