vigilante-create-issue

name	vigilante-create-issue
description	Help a human author write an implementation-ready GitHub issue that Vigilante can execute reliably.

Vigilante Create Issue

Overview

Use this skill when a human wants to write or refine a GitHub issue that Vigilante will later implement. The default goal is to turn a vague request into an issue with enough behavioral detail, constraints, and verification criteria for a headless coding agent to execute safely, then create that issue on GitHub. If creation is not possible, fall back to returning a ready-to-file issue body. The goal is not to design the full solution for them.

Outcome

Produce a GitHub issue that is:

• classified as a feature, bug, or task before the draft is finalized
• specific about the problem and why it matters
• grounded in repository or product context
• explicit about expected behavior and non-goals
• realistic about implementation flexibility and hard constraints
• testable through concrete acceptance criteria
• clear about validation and regression coverage
• created on GitHub by default when the target repository can be resolved and gh issue creation is available
• returned as a polished Markdown draft only when the user explicitly asks for draft-only output or issue creation is blocked

Workflow

1. Clarify the request before writing

• Identify the change the user actually wants.
• Ask for missing repository, product, or user context when it affects implementation.
• Separate required behavior from guesses or preferences.

2. Classify the request before finalizing the issue body

• Decide whether the request is best treated as a feature, bug, or task.
• Base the classification on the user's stated problem and desired outcome rather than implementation details.
• If the request is ambiguous, infer the most likely type and state briefly that the type was inferred.
• Use the selected type to decide which details are required in the issue body, not just to append a label.

3. Resolve the target repository before finalizing output

• Prefer local git context first when the user is working inside a repository.
• Otherwise use an explicitly provided repository slug or URL.
• If the repository cannot be resolved confidently, say so briefly and fall back to returning the ready-to-file issue body instead of guessing.

4. Frame the issue around execution

• Write for the agent that will implement the issue later, not for a broad brainstorming audience.
• Prefer observable behavior over vague aspirations.
• Note any constraints that must be preserved: CLI flags, APIs, config compatibility, UX expectations, rollout limits, or performance boundaries.

5. Capture implementation guidance without over-constraining

• Include likely solution paths when they materially reduce ambiguity.
• Mark which implementation details are required and which are flexible.
• Call out known tradeoffs or rejected alternatives when relevant.

6. Make completion testable

• Convert expectations into pass/fail acceptance criteria.
• State what tests should be added or updated.
• Mention the key regressions or failure modes that must be prevented.

7. Create the GitHub issue by default

• When the repository is known and the user did not explicitly ask for draft-only output, use vigilante gh issue create to open the issue.
• Prefer vigilante gh api repos/{owner}/{repo}/issues over vigilante gh issue create when opening the final issue so Vigilante can set GitHub's native issue type with the request body type field.
• Map Vigilante's internal classifications explicitly to GitHub's native issue types: feature -> Feature, bug -> Bug, task -> Task.
• Treat the native GitHub issue type as the source of truth whenever the repository supports it.
• When the draft explicitly says the new issue is a follow-up, child, or sub-issue of a specific existing issue, carry that parent issue number through issue creation.
• After the base issue is created, attach it as a native GitHub sub-issue of that parent with vigilante gh api --method POST repos/{owner}/{repo}/issues/{parent_issue_number}/sub_issues -f sub_issue_id={created_issue_id}.
• Only create a native relationship when the parent mapping is explicit and low-ambiguity; incidental issue-number mentions in prose are not enough.
• If native sub-issue creation fails or the repository does not support it, keep the created issue, preserve the body text reference, and make the fallback explicit in the final response.
• Use the polished Markdown body as the issue content instead of stopping at the draft.
• In the final response, include the created issue URL or issue number and keep the body available if useful.

8. Fall back cleanly when issue creation is blocked

• If issue creation cannot be completed because repository context is missing, gh auth is unavailable, network access is blocked, or sandbox restrictions prevent GitHub access, say so briefly and return the ready-to-file Markdown issue instead.
• If the repository rejects the native type field because issue types are unavailable or unsupported, retry issue creation without the native type and make the fallback explicit in the final response.
• If the native sub-issue relationship request is rejected or unsupported, do not fail the overall issue creation flow; keep the new issue and report that the relationship fell back to body-only text.
• If the environment supports requesting escalation for GitHub/network access, do that before giving up.
• If the user explicitly asks for a draft only, honor that request and do not create the issue.
• Keep failure messaging short, specific, and factual.

Issue Type Guidance

• Always classify the request as feature, bug, or task before finalizing the issue.
• When creating the issue on GitHub, write that classification into GitHub's native issue type field whenever the repository supports it.
• Do not use labels or issue-body text as the primary type representation when the native issue type is set successfully.
• Do not infer parent/child issue links from vague wording or unrelated issue references.
• Only include an Issue Type: ... line in the issue body when returning a draft without creating the issue, or when native issue types are unavailable and the fallback needs to preserve the classification explicitly.
• When the type was inferred from an ambiguous request, note that clearly, for example Issue Type: task (inferred), but only in the draft/fallback body when that line is needed.
• For bug issues, prioritize current behavior, expected behavior, impact, reproduction clues, and regression risk.
• For feature issues, prioritize the desired user-facing outcome, scope boundaries, and non-goals.
• For task issues, prioritize the concrete deliverable, operational context, constraints, and completion conditions.

Required Sections

Every issue draft should cover these sections when relevant:

1. Problem statement

• What is wrong, missing, or desired?
• Why does this matter now?

2. Context

• What repository, product, or workflow context does the implementer need?
• What is the current behavior?
• Who is affected?
• What assumptions or constraints are already known?

3. Desired outcome

• What should be true after implementation?
• What is explicitly out of scope?

4. Possible implementation approaches

• What are the most plausible solution paths?
• Which details are required versus flexible?
• What tradeoffs should the implementer understand?

5. Acceptance criteria

• Use explicit, testable statements.
• Prefer behavior-focused checks over generic wording like "works correctly."

6. Testing expectations

• State which test layers matter: unit, integration, CLI, workflow, end-to-end, or manual verification.
• Mention critical regressions and failure modes that need coverage.

7. Operational or UX considerations

• Include logging, migrations, config compatibility, docs, observability, rollout, or backward compatibility concerns when applicable.

Issue Quality Rules

• Do not leave "should support X" statements undefined when the expected behavior can be stated concretely.
• Do not hide key constraints inside prose if they materially affect implementation.
• Do not invent repository details that were not provided. Flag missing context instead.
• Do not overload the issue with speculative architecture unless the decision matters to execution.
• Do include non-goals so the eventual implementation stays narrow.
• Do include exact commands, files, components, or workflows when they are already known.

Stacked-PR Base Branch

• When the user wants the new issue to be implemented on top of an existing in-flight branch (a stacked PR), add a single top-level line to the issue body of the form Base branch: <branch-name>.
• Use this line only when the user explicitly asks to stack on another branch. Do not infer stacking from prose mentions of other branches, related issue numbers, or native sub-issue relationships.
• The branch name must exist on the repository remote when implementation runs; the implementation skills will fail the session if it does not.
• Without this line, Vigilante branches off and targets the watch target's base branch as today.

Recommended Questions To Ask

Use these to tighten the issue before drafting:

• What exactly should change?
• What currently happens instead?
• Why is the change needed?
• What constraints must the implementation respect?
• Which solution options are acceptable, and which are not?
• How will we know the issue is done?
• What tests prove the change works?
• What regressions must be prevented?

Output Template

Use this structure for the issue body:

## Summary
<One short paragraph describing the problem and desired change.>

Issue Type: <feature | bug | task>[ (inferred)]  <!-- include only for draft-only or documented fallback output -->

## Problem
- <What is wrong, missing, or desired>
- <Why it matters>

## Context
- <Current behavior>
- <Relevant repo, product, or workflow details>
- <Constraints or assumptions>

## Desired Outcome
- <Expected end-state>
- <Non-goals or out-of-scope items>

## Implementation Notes
- <Likely approach or options>
- <Required constraints vs flexible details>
- <Tradeoffs, if relevant>

## Acceptance Criteria
- [ ] <Specific observable behavior>
- [ ] <Specific observable behavior>

## Testing Expectations
- <Tests to add or update>
- <Failure modes or regressions to cover>

## Operational / UX Considerations
- <Docs, logging, migration, compatibility, rollout, observability, etc.>

Type-specific reminders:

• bug: include current behavior, expected behavior, impact, and reproduction clues when available.
• feature: include the desired outcome, boundaries, and explicit non-goals.
• task: include the deliverable, operational context, constraints, and concrete done criteria.

Final Checks

Before creating the issue or returning the fallback draft, verify that:

• the problem is understandable without extra oral context
• the selected issue type is feature, bug, or task
• the native GitHub issue type is used when the issue is created in a repository that supports it
• explicit follow-up or child relationships are attached as native GitHub sub-issues when the parent issue is clearly identified
• ambiguous issue references do not create native parent/child links
• any Issue Type: line in the body is reserved for draft-only or explicit fallback output
• the desired outcome is observable
• the acceptance criteria are testable
• the testing section names the expected validation
• the body includes the type-specific details that matter for the selected class instead of only a label
• the issue gives Vigilante enough direction to implement without guessing the basics
• the target repository is known before attempting issue creation
• the final response includes the created issue URL or number when creation succeeds
• the final response says whether the native sub-issue relationship was created or whether issue creation fell back to body-only linking
• the fallback response states briefly why issue creation was not completed when it fails