gentle-ai-issue-creation

Issue Creation

Core Rule

Discover the target repository's contribution workflow before proposing or publishing. YAML Issue Forms are the format authority for the default automated path: materialize reviewed answers into a private BODY_FILE and publish with --body-file.

Safe Discovery

Run read-only checks first:

gh auth status
REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)"
REPO_URL="$(gh repo view --json url -q .url)"
HOST="${REPO_URL#*://}"
HOST="${HOST%%/*}"
TARGET="$HOST/$REPO"
gh repo view --json nameWithOwner,url,hasDiscussionsEnabled,hasIssuesEnabled,isBlankIssuesEnabled
git ls-files README.md CONTRIBUTING.md CONTRIBUTING.* .github/CONTRIBUTING.md .github/ISSUE_TEMPLATE .github/ISSUE_TEMPLATE/config.yml
gh api --hostname "$HOST" --paginate "repos/$REPO/labels?per_page=100" --jq '.[].name'

Inspect README.md, contribution instructions, .github/ISSUE_TEMPLATE/config.yml contact links, forms, labels, and open and closed issues. For questions/support, follow repository-prescribed Discussions/contact routing when available; otherwise ask or stop. Complete target verification for REPO, HOST, and TARGET. Fail closed before mutation when authentication, target verification, issue availability, policy, form selection, or required metadata is missing or ambiguous. A blank fallback is allowed only when isBlankIssuesEnabled is explicitly true.

Build LABEL_ARGS only from reviewed labels that exist and policy permits the actor to apply:

LABEL_ARGS=()
LABEL_ARGS+=(--label "$LABEL") # Repeat only for each permitted discovered label.

Duplicate And Form Decision

1. Describe the report in one sentence, derive QUERY, then complete one duplicate search across open and closed issues:

   gh issue list --repo "$TARGET" --state all --search "$QUERY" --limit 1000
   

   If results are saturated or completeness is uncertain, narrow the read-only search or stop. Comment on a confirmed duplicate instead of creating one. Before commenting on a confirmed duplicate, perform the same privacy scan/redaction on the exact comment body as for publication.

2. Select one repository-provided form only when its declared purpose matches. If multiple forms match and policy does not distinguish them, stop and request that decision.

3. For a YAML form, read its schema and establish controls in declared order. Support only input, textarea, dropdown, and checkboxes. Markdown controls are non-answer guidance: honor their visible instructions when collecting and materializing adjacent answers, but do not render them as response sections. Fail closed before mutation on malformed, unsupported, missing, or ambiguous required structure or answers. A malformed schema, or missing or ambiguous required answers, fail closed: do not open a browser or mutate. A browser handoff is available only when the user explicitly requests browser completion or a syntactically valid selected form cannot safely/faithfully be represented by the automated path; otherwise report why automation is unsafe and stop.