Gentleman-Programming/gentle-ai-issue-creation

Criação de Issues

Regra Principal

Descubra o fluxo de contribuição do repositório de destino antes de propor ou publicar. Os Formulários de Issue em YAML são a autoridade de formato para o caminho automatizado padrão: materialize respostas revisadas em um BODY_FILE privado e publique com --body-file.

Descoberta Segura

Execute verificações somente leitura primeiro:

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'

Inspecione README.md, instruções de contribuição, links de contato em .github/ISSUE_TEMPLATE/config.yml, formulários, labels, e issues abertas e fechadas. Para perguntas/suporte, siga o roteamento de Discussões/contato prescrito pelo repositório quando disponível; caso contrário, pergunte ou pare. Complete a verificação do destino para REPO, HOST e TARGET. Falhe de forma segura antes da mutação quando autenticação, verificação de destino, disponibilidade de issue, política, seleção de formulário ou metadados necessários estiverem faltando ou forem ambíguos. Um fallback em branco é permitido apenas quando isBlankIssuesEnabled for explicitamente verdadeiro.

Construa LABEL_ARGS apenas a partir de labels revisadas que existem e a política permite que o ator aplique:

LABEL_ARGS=()
LABEL_ARGS+=(--label "$LABEL") # Repita apenas para cada label descoberta e permitida.

Decisão de Duplicata e Formulário

1. Descreva o relatório em uma frase, derive QUERY, então complete uma busca por duplicatas em issues abertas e fechadas:

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

   O agente deve completar a busca por duplicatas proativamente e reter evidências do resultado. Se os resultados estiverem saturados ou a completude for incerta, restrinja a busca somente leitura ou pare. Comente em uma duplicata confirmada em vez de criar uma nova. Antes de comentar em uma duplicata confirmada, realize a mesma verificação/redação de privacidade no corpo exato do comentário como para publicação.

2. Selecione um formulário fornecido pelo repositório apenas quando seu propósito declarado corresponder. Se vários formulários corresponderem e a política não os distinguir, pare e solicite essa decisão.

3. Para um formulário YAML, leia seu esquema e estabeleça controles na ordem declarada. Suporte apenas input, textarea, dropdown e checkboxes. Controles Markdown são orientações não relacionadas a respostas: honre suas instruções visíveis ao coletar e materializar respostas adjacentes, mas não os renderize como seções de resposta. Falhe de forma segura antes da mutação em estrutura ou respostas necessárias malformadas, não suportadas, ausentes ou ambíguas. Um esquema malformado, ou respostas necessárias ausentes ou ambíguas, falham de forma segura: não abra um navegador ou faça mutação. Uma transferência para o navegador está disponível apenas quando o usuário solicitar explicitamente a conclusão pelo navegador ou um formulário selecionado sintaticamente válido não puder ser representado de forma segura/fiel pelo caminho automatizado; caso contrário, relate por que a automação é insegura e pare.

Controle	Tratamento Necessário
input / textarea	Preserve o rótulo visível. Exija uma resposta quando validations.required for verdadeiro; caso contrário, renderize _No response_.
dropdown	Preserve rótulos e opções visíveis. Exija o texto exato da opção selecionada; seleção única tem uma seleção, e seleção múltipla preserva seleções na ordem das opções declaradas. Um dropdown obrigatório precisa de pelo menos uma seleção válida; um dropdown opcional sem seleção renderiza _No response_.
checkboxes	Preserve o rótulo visível e cada opção como - [x] ou - [ ] na ordem declarada. Imponha checkboxes obrigatórias individualmente. Para opções operacionais verificáveis pelo agente, complete proativamente a ação e marque-a apenas com evidências retidas; o agente pode atestar explicitamente apenas seu próprio trabalho apoiado por evidências e não deve atribuir suas ações ao usuário. Fatos pessoais, consentimento, declarações legais e outras afirmações de usuário em primeira pessoa exigem afirmação explícita do usuário; exija afirmação explícita em primeira pessoa para tais declarações do usuário. Não marque checkboxes indiscriminadamente: uma solicitação para publicar não afirma nenhuma checkbox.

Para cada resposta, renderize ### <rótulo visível> seguido pelo seu valor materializado. Para textarea.attributes.render, coloque a resposta entre fences com a linguagem declarada e um fence longo o suficiente para seu conteúdo. Nunca invente respostas, seleções, confirmações ou rótulos.

Um modelo Markdown pode ser completado apenas a partir de evidências conhecidas no mesmo BODY_FILE privado. Se nenhum modelo correspondente existir, use o fallback em branco estruturado revisado apenas quando issues em branco estiverem explicitamente habilitadas; caso contrário, pare sem publicar.

Revisão e Publicação

Antes da única tentativa de criação, revise o destino, título, formulário selecionado ou fallback permitido, corpo exato e labels permitidas. O agente deve completar a verificação/redação de privacidade do corpo exato imediatamente antes da publicação e reter evidências disso: substitua nomes de projetos privados, nomes de usuário, nomes de host, caminhos iniciais, credenciais e endereços de rede privados com placeholders úteis sem remover a estrutura de reprodução.

Crie um diretório temporário exclusivo do proprietário fora do repositório para ambos os arquivos privados; restrinja-o ao usuário atual e limpe ambos os arquivos em cada saída/resultado:

umask 077
REPO_ROOT="$(git rev-parse --show-toplevel)" || exit 1
REPO_ROOT="$(cd "$REPO_ROOT" && pwd -P)" || exit 1
if [ "$REPO_ROOT" = "/" ]; then
  printf '%s\n' "Diretório temporário está dentro do repositório" >&2; exit 1
fi
TMP_DIR="$(TMPDIR=/tmp mktemp -d /tmp/gentle-ai-issue.XXXXXXXX)" || exit 1
trap 'rm -rf -- "$TMP_DIR"' EXIT
TMP_DIR_REAL="$(cd "$TMP_DIR" && pwd -P)" || exit 1
case "$TMP_DIR_REAL/" in
  "$REPO_ROOT/"*) printf '%s\n' "Diretório temporário está dentro do repositório" >&2; exit 1 ;;
esac
chmod 700 "$TMP_DIR_REAL"
BODY_FILE="$TMP_DIR_REAL/body.md"
READBACK_FILE="$TMP_DIR_REAL/readback.json"

Faça uma tentativa de mutação através do caminho automatizado e publique exatamente uma vez:

gh issue create --repo "$TARGET" --title "$TITLE" --body-file "$BODY_FILE" "${LABEL_ARGS[@]}"

Quando a conclusão pelo navegador estiver disponível sob a decisão de formulário acima, uma transferência opcional e separada para o navegador pode abrir o formulário do repositório. Nunca é prova de publicação e nunca é uma resposta a esquemas malformados ou respostas necessárias ausentes/ambíguas:

gh issue create --repo "$TARGET" --web

Não tente novamente em caso de timeout, falha de rede, identidade ausente ou outro resultado incerto. Capture o número da issue retornado, então leia-o de volta do host de destino verificado antes de relatar sucesso:

gh issue view "$NUMBER" --repo "$TARGET" --json number,url,title,body,state,labels >"$READBACK_FILE"

Confirme que a leitura de volta identifica a issue no host de destino e que título e corpo correspondem após normalização apenas de CRLF para LF e nova linha final. Relate confirmed apenas após esta leitura de volta do host de destino. Caso contrário, relate no_write quando uma rejeição autoritativa provar que nenhuma issue foi criada, ou unknown e pare todas as mutações posteriores.

Triagem

Antes de aprovar ou fechar uma issue, verifique se ela é concreta, não duplicada, suficientemente evidenciada, dentro do escopo e consistente com a política de label/status do repositório. Se qualquer ponto for incerto, mantenha o estado de revisão do repositório e solicite a menor evidência faltante.