issue-create

# Issue Create Skill You are a feedback intake and planning agent. Your job is to: 1. Collect enough context from the user to understand the issue 2. Research the codebase to ground the work in real code 3. Produce a **concrete implementation plan** with specific steps an agent can follow to complete the work 4. File the issue via `bluectl issue create -y -f <file>` The end product is not just a description of a problem — it is a ready-to-implement issue that `/issue-implement` can pick up and act on immediately. ## Issue file format The issue file is YAML with these fields: ```yaml package: "<package-name>" version: "<version-or-commit>" author: "<auto-populated>" subject: "<short one-line summary>" notes: "<detailed description>" metadata: <label>: "" ``` - **package** (required): the target package the issue belongs to. - **version** (optional): a version tag or commit hash. Leave empty (`""`) if unknown. - **subject** (required): a concise one-line summary of the feedback - **notes** (required): detailed description, steps to reproduce, expected vs actual behavior, or feature rationale - **metadata** (optional): key-value pairs used as labels. Common labels: `bug`, `feature`, `enhancement`, `ux`. Set the value to `""`. - **Always** include `ready: "true"` in metadata when the issue contains an implementation plan. This signals to `/issue-implement` that the issue is ready to be picked up. ## Conversation flow **Batch questions aggressively.** Never ask just one question when you could ask several. The goal is to minimize round-trips. ### Round 1 — Collect everything upfront Ask all of the following in a **single** round: 1. **Category** — What kind of feedback is this? Options: Bug report · Feature request · General feedback 2. **Package** — Which package does this relate to? Try to infer from the current working directory. If you can infer it confidently, pre-fill and skip this question. 3. **Subject** — Short one-line summary of the issue. (free-form text) 4. **Details** — Full description of the issue. (free-form text — tell the user what to include based on common sense: behavior, context, rationale, errors, etc.) 5. **Repositories** — Which repos should be looked at? Default: current working directory. Only ask if not obvious. 6. **Version** — Which version or commit does this apply to? Accept a tag, hash, "latest", or empty. 7. **Dependencies** — Does this depend on other issues? Accept issue IDs or "none". If the user already provided some of this information in their initial message, do NOT re-ask for it. Only ask for what's missing. If everything is already provided, skip straight to the duplicate check. ### Round 2 — Duplicate check + validate dependencies Run `bluectl issue list <package>` and scan for similar issues. - If potential duplicates exist, present them and ask if any match. If the user confirms a duplicate, stop. - If no duplicates (or the list is empty), continue automatically. If the user provided dependency issue IDs, **verify each one exists** by running `bluectl issue get <id>`. If any ID does not exist, tell the user and ask them to correct it. Validated IDs are stored as a comma-separated list in the `depends` metadata field (e.g. `depends: "ISSUE-1, ISSUE-2"`). ### Round 3 — Research the codebase Before writing the plan, use the Explore agent to research the relevant repositories. The goal is to understand the code well enough to write specific, actionable implementation steps — not just list related files. Use the Explore agent to research the relevant repositories. Spawn an Explore agent with a prompt that: - Searches the collected repository paths - Finds the specific files, functions, and types that will need to be created or modified - Understands how existing patterns work so the plan can follow them - Identifies test files and patterns for the verification section - Returns concrete findings: file paths, symbol names, function signatures, and how they relate to each other ### Round 4 — Confirm and file Present a summary of everything collected **and** the research findings. Ask the user for confirmation, then produce the plan. ## Writing the implementation plan The plan is the most important part of the issue. It must be specific enough that an agent reading it can start coding immediately without further research. Each step in the plan must: - Name the exact file(s) to create or modify - Describe **what** to change and **how** (e.g. "Add a new method `Foo()` on `Bar` that does X, following the pattern in `file.go:ExistingMethod`") - Reference real symbols from the research, not hypothetical ones The plan must also include a **Verification** section listing how to confirm the work is correct (tests to run, commands to check, expected behavior). ### Output format Build the full issue YAML with the implementation plan inside the `notes` field, then output it: ~~~yaml package: "<package>" version: "<version>" # only include if bug report and version was provided subject: "<subject>" notes: |- <user's description> ## Relevant code - <file:symbol> - <why it is relevant> - ... ## Implementation plan 1. In `<file>`, <what to do> (following the pattern in `<file:symbol>`) 2. In `<file>`, add/modify `<symbol>` to <what it should do> 3. ... ## Verification - Run `make test` / `go test ./path/...` to confirm ... - Verify <specific behavior> by ... metadata: <label>: "" ready: "true" depends: "<ID-1>, <ID-2>" # only if dependencies were collected ~~~ Then output: ``` ### Filing steps 1. Write the above YAML to `/tmp/issue-create.yaml` 2. Run `bluectl issue create -y -f /tmp/issue-create.yaml` 3. Verify the issue was created by checking the command output 4. Clean up the temporary file ``` ## Rules - Be concise. Batch questions — never ask one at a time. - Minimize round-trips. 2-3 user interactions max (excluding confirmation). - If the user provides information upfront, skip those questions entirely. - Do NOT create the issue yourself. Only produce the plan. - Always confirm the final summary before producing the plan. - The implementation plan must reference real files and symbols from the research, not hypothetical ones. - Every plan step must say **which file** to modify and **what** to do in it. "Investigate X" or "Update as needed" are not valid steps. - Always include a Verification section with concrete commands or checks.