benkruger/flow-create-issue

Flow Create Issue

Capture a brainstormed solution from the current conversation and file it as a pre-planned GitHub issue. The issue includes an Implementation Plan section (Context, Exploration, Risks, Approach, Dependency Graph, Tasks) that the Plan phase extracts directly — no re-derivation needed.

This skill requires prior brainstorming context in the conversation. The user must have already explored the problem (typically via /decompose:decompose) and iterated on a solution before invoking this skill.

Usage

/flow:flow-create-issue
/flow:flow-create-issue --force-decompose

• /flow:flow-create-issue — start from the Conversation Gate
• /flow:flow-create-issue --force-decompose — force a fresh decompose even when prior implementation-focused output exists in the conversation

Concurrency

This skill creates shared GitHub state (issues). Issue creation is idempotent by title — if an issue with the same title already exists, the user should be warned before filing a duplicate.

Announce

At the very start, output the following banner in your response (not via Bash) inside a fenced code block:

```text
──────────────────────────────────────────────────
  FLOW v1.1.0 — flow:flow-create-issue — STARTING
──────────────────────────────────────────────────
```

---

Conversation Gate

Before entering the pipeline, verify that the current conversation contains brainstorming context — a problem that was explored, a solution that was discussed and agreed upon. This skill captures solutions, it does not discover them.

Signals that context exists — proceed to Capture:

• Prior /decompose:decompose output in the conversation
• Extended back-and-forth about a problem and its solution
• An agreed approach, design, or set of changes discussed
• The user explicitly says "file it", "create an issue", or similar

Signals that context is missing — reject:

• The skill was invoked with a bare problem description and no prior discussion
• No decompose output or design iteration is visible in the conversation
• The conversation just started with this invocation

<HARD-GATE>

If no brainstorming context exists, output this guidance and stop:

"This skill captures a brainstormed solution as a pre-planned issue. Start by running /decompose:decompose to research the problem, iterate on a solution, then invoke /flow:flow-create-issue when you have an agreed approach."

Do not proceed to Capture, propose direct edits, commit changes, or take any action outside this skill without brainstorming context in the conversation.

</HARD-GATE>

---

Capture

Generate a short session ID by running ${CLAUDE_PLUGIN_ROOT}/bin/flow generate-id via the Bash tool. This ID scopes the body file path (.flow-issue-body-<id>) so concurrent flow-create-issue invocations cannot collide on the same temp file.

Capture the problem sections from the conversation context. Synthesize the discussion into these structured sections in working memory — do not re-analyze or re-explore, just distill what was already discussed:

• Problem — What is broken, missing, or inadequate. Include observable behavior, evidence from the codebase (file paths, line numbers), and user impact. Grounded in the exploration already done in the conversation.
• Acceptance Criteria — Binary, testable conditions. Pass/fail with no subjective judgment.
• Files to Investigate — Real file paths verified during the conversation's codebase exploration. Include a brief note on why each is relevant.
• Out of Scope — Explicit boundaries to prevent scope creep.
• Context — Business reason, architectural constraints, or design decisions.

---

Decompose

Check the conversation for prior /decompose:decompose output that is implementation-focused. Implementation-focused output contains all of: task nodes with file targets, implementation ordering (dependency graph or sequential tasks), and concrete code changes or insertion points. Problem-analysis output — containing only analysis, questions, or high-level framing without actionable task structure — does not qualify.

If the conversation contains implementation-focused decompose output AND --force-decompose was NOT passed: the existing decompose synthesis is sufficient. Skip the decompose invocation below and proceed directly to Transform + Draft.

If the conversation contains only problem-analysis decompose output (no tasks, no file targets), or no prior decompose output exists, or --force-decompose was passed: invoke decompose:decompose via the Skill tool with an implementation-focused prompt. The prompt must make clear that the problem and solution are already agreed — decompose should structure the implementation into tasks, not re-analyze the problem.

Example prompt structure:

"Given the following agreed solution, decompose the implementation into ordered tasks with dependencies, approach, and file targets. The problem is already understood — focus on structuring the work.

[Summary of the agreed solution from the conversation]

[Key files and patterns identified during brainstorming]"

The decompose output produces a structured DAG with nodes, dependencies, and a synthesis — this becomes the foundation for the Implementation Plan.

---

Transform + Draft

Take the decompose synthesis from the conversation — either from a prior /decompose:decompose invocation (when the Decompose step skipped a fresh invocation) or from the invocation you just ran — and transform it into an Implementation Plan section that matches the plan file format used by flow-plan. The Implementation Plan must contain these subsections:

• Context — What the user wants to build and why
• Exploration — What exists in the codebase, affected files, patterns discovered
• Risks — What could go wrong, edge cases, constraints
• Approach — The chosen approach and rationale
• Dependency Graph — Table of tasks with types and dependencies:

| Task | Type | Depends On |
|------|------|------------|
| 1. Write tests | test | — |
| 2. Implement feature | implement | 1 |

• Tasks — Ordered implementation tasks, each with:
  • Description of what to build
  • Files to create or modify
  • TDD notes (what the test should verify)

Tasks must use #### Task N: heading format (these become ### Task N: headings in the plan file after heading promotion by flow-plan).

Combine into Issue Body

Combine the captured problem sections with the Implementation Plan into a single issue body in working memory. The section order must be:

Problem (from capture) → Acceptance Criteria (from capture) → Implementation Plan (from transform, wrapped between sentinels — containing Context, Exploration, Risks, Approach, Dependency Graph, Tasks subsections) → Files to Investigate (from capture) → Out of Scope (from capture) → Context (from capture — business reason).

Each top-level section uses ## headings. The Implementation Plan's subsections use ### headings. Task entries within the Tasks subsection use #### headings.

Wrap the Implementation Plan in FLOW-PLAN sentinels. Place the literal HTML comment <!-- FLOW-PLAN-BEGIN --> on its own line immediately before the ## Implementation Plan heading, and the literal HTML comment <!-- FLOW-PLAN-END --> on its own line immediately after the last Task entry (before the next ## heading). The sentinels delimit the bytes that bin/flow plan-from-issue will extract verbatim and write to .flow-states/<branch>/plan.md when the issue is later picked up via /flow:flow-start #N. Without the sentinel pair, plan-from-issue rejects the issue with plan_markers_missing and the flow halts.

The wrapped block looks like this in the issue body:

<!-- FLOW-PLAN-BEGIN -->
## Implementation Plan

### Context
...

### Exploration
...

### Tasks

#### Task 1: ...
...
<!-- FLOW-PLAN-END -->

Draft Presentation

Present the full draft inline in the response — both title and body. Do not tell the user to look at a file. Render it as a formatted markdown block so the user can review every detail.

---

File

<HARD-GATE>

After presenting the draft, ask the user to confirm via AskUserQuestion with structured parameters:

• question: "Review the draft above. Ready to file?"
• header: "File Issue"
• options:
  • label: "File issue", description: "File against the current repo with the decomposed label"
  • label: "Revise draft", description: "Edit the draft based on your feedback"
  • label: "Cancel", description: "Stop without filing an issue"

Do not file the issue, propose direct edits, commit changes, or take any action outside this skill without explicit user approval via AskUserQuestion — even if the answer appears obvious from context.

If "File issue" → proceed to Filing below.

If "Revise draft" → revise based on the user's feedback and re-present the draft. If the feedback is substantial (changes the problem understanding or approach), re-run decompose:decompose with the updated understanding and re-transform. If the feedback is editorial (wording, scope adjustments), edit the draft directly. When in doubt, treat the feedback as substantial and re-run decompose:decompose — the safe default is the conservative action (per .claude/rules/skill-authoring.md "Safe Defaults for Subjective Classification"); editing a draft built on a misaligned decompose ships an incorrect Implementation Plan. After revising, re-present the draft and ask the same AskUserQuestion. Iterate as many times as needed.

If "Cancel" → stop without filing. Do not write the body file. Do not output the COMPLETE banner.

</HARD-GATE>

---

Filing

Write the issue body to .flow-issue-body-<id> in the project root using the Write tool. Then file it against the current repo (no --repo flag — flow-create-issue always files where the user is):

${CLAUDE_PLUGIN_ROOT}/bin/flow issue --title "<issue_title>" --body-file .flow-issue-body-<id> --label decomposed

Record the issue in the state file (no-op if no FLOW feature is active):

${CLAUDE_PLUGIN_ROOT}/bin/flow add-issue --label decomposed --title "<issue_title>" --url "<issue_url>" --phase flow-create-issue

Display the issue URL to the user, then output the COMPLETE banner:

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ FLOW v1.1.0 — flow:flow-create-issue — COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Hard Rules

• Never file an issue without explicit user approval — the AskUserQuestion before filing is the mandatory gate
• Never tell the user to "look at" a file — render all content inline
• Never use Bash to print banners — output them as text in your response
• The issue body must be self-contained — a fresh session with no memory of this conversation must be able to execute it
• Always use the Write tool to create body files (.flow-issue-body-<id>) — never pass body text as a CLI argument
• Never delete the body file — the bin/flow issue script handles cleanup
• The Implementation Plan section must use heading levels that match the plan file format after promotion by flow-plan (### in the issue becomes ## in the plan file)