issue-report

issue-report

A skill that accepts multiple bug reports and feature requests at once, clarifies them through interviews and parallel investigation, groups them into units that do not conflict, and registers/integrates them as GitHub issues.

Purpose

Because the development flow is \"parallel development in worktrees starting from issues,\" conflicts occur frequently when the change scopes of issues overlap. This skill defines the unit of an issue as follows:

1 issue = a unit whose expected change area (touch set) is independent = the division unit for one worktree

Therefore, rather than the conventional \"1 task = 1 issue,\"tasks that may interfere with each other are combined into one issue, and independent tasks are separated. Also, reports whose scope overlaps with an existing open issue are not made into new issues but insteadintegrated into the body of the existing issue(this serves both to prevent duplicate registration and to consolidate multiple perspectives on the same task).

At the same time, the conventional purpose is also maintained: preventing developer rework from having to ask again due to vague issues (ones where it is unclear which screen is meant, there are no reproduction steps, there is no distinction between expected and actual, or the purpose of the request is unclear).

This skill operates as a control plane. The parent acts as PM and handles only user dialogue, gates, progress management, and delivery of artifact files, while the actual work of decomposition, investigation, matching, grouping, drafting, and registration is delegated to workers (the sub-agent mechanism provided by the environment). With this structure, even if the number of cases included in a report is large, it can be handled without increasing the number of interactions or context consumption.

Intended users

Behave on the premise that the person invoking this skill is a non-engineer. All questions, confirmations, and guidance must be given without technical terms (components, APIs, repositories, commits, etc.), using the words the user sees on screen (screen names, button and menu wording, displayed messages). A single report may contain multiple problems or requests.

Handling additional instructions

Treat the content passed by the user as arguments (in Claude, /issue-report arguments; in Codex, $issue-report arguments) as the initial description of the problem or request, and apply it with priority over other policies in this skill. However, if it violates important constraints such as \"do not write to GitHub without approval\" or \"do not decide solutions or implementation specifications,\" do not execute it and stop immediately to ask for confirmation. If the arguments are empty, start by inviting the user to speak freely: \"What problems or requests do you have? It is fine if there are many.\"

Most important compliance rules

1. The unit of an issue is \"a unit whose expected change area is independent\". Overlap determination is performed at the area level (screen / route / module / directory prefix), andif there is any possibility of interference, lean toward integration(for details, see references/grouping-rules.md）
2. The parent devotes itself to being PM. The parent is responsible only for user dialogue, gate decisions, phase progression management, and delivery of artifact files. The parent must not take on the semantic judgment and actual work of case decomposition, code investigation, matching against existing issues, grouping, body drafting, or registration execution.
3. Artifacts between workers are all delivered as files under the execution directory.. The parent retains only file paths and count summaries, and does not load the details of investigation results or the bodies of all open issues into its own context.
4. User dialogue (decomposition confirmation, specification confirmation, hearings, approval) is conducted only by the parent.. Dialogue with the user must not be delegated to workers.
5. Do not write anything to GitHub until explicit approval from the user is obtained.. Approval is given for the registration plan in Phase 7.
6. Always pass only "1 packet = 1 issue operation" to execution workers.. Operations on multiple issues or an entire plan must not be passed to a single worker at the same time.
7. Estimate the impact area, but do not decide on solutions or implementation specifications.. Estimation is limited to area estimation for grouping purposes; do not ask questions about how to fix things or what specifications to use, and do not write them in issues either.
8. Determination of cross-cutting issues is based solely on the presence or absence of the label scope:cross-cutting .. Do not judge by title wording (the【横断】 prefix is a display for humans)
9. All questions can be skipped.. Write items you did not understand honestly as "unknown", and do not fill them in with guesses.
10. Do not use technical terms or file paths in questions, confirmations, or explanations to the user.(the only exception is the "developer reference information" in the issue body). Also explain grouping reasons in screen-oriented language such as "because they relate to the mechanisms of the same screen".

Role division

Role	Responsibility	Number of workers / parallelism
parent（PM）	User dialogue, gates, progression management, file delivery	1
Decomposition worker	Decompose the report text into a case list (cases.json)	1 worker
Investigation worker	Read-only code investigation per case → return structured candidate target screens, expected change areas, confidence, and missing information	Parallel for the number of cases
Issue index worker	gh issue list --state open Generate an index (issue-index.json) from all entries	1 worker (concurrent with investigation workers)
Classification agent	From investigation results + index, perform grouping, merge-destination determination, and cross-cutting determination (grouping-plan.json). Use a sub-agent with high reasoning ability (default example: Oracle)	1 worker
Drafting worker	Draft the issue body (new) or the merged body (for rewriting) for each group	Run in parallel for the number of groups
Execution worker	After approval, 1 issue operation = 1 packet and gh issue create / gh issue edit --body execute	Run in parallel for the number of groups

Execution pipeline

[Phase 0] 受け取り                      (parent)
    ↓
[Phase 1] ケース分解                    (分解ワーカー) → 分解の一括確認 (parent↔ユーザー)
    ↓
[Phase 2] 並列実態調査 ∥ issue索引作成   (調査ワーカー×N ∥ 索引ワーカー)
    ↓
[Phase 3] 対象の特定確認                (parent↔ユーザー: 確度トリアージ)
    ↓
[Phase 4] 課題のヒアリング              (parent↔ユーザー: 不足情報駆動・スキップ可)
    ↓
[Phase 5] グルーピング・統合判定         (分類エージェント)
    ↓
[Phase 6] 本文起草                      (起草ワーカー×G)
    ↓
[Phase 7] 登録計画の承認 → 登録実行      (parent↔ユーザー → 実行ワーカー×G)
    ↓
[完了] 登録・更新した issue の URL 一覧を報告

The details of each phase (what to request from workers, the schema of deliverable files, gate conditions, dialogue scale design) follow references/orchestration-protocol.md .

Degradation in environments without subagents

In harnesses that do not provide a subagent mechanism (e.g., Codex), the above role separation is executed in a degraded manner within a single parent. Even if role separation does not physically exist, maintain the discipline within yourself:

• The parent itself executes Phases 0–7 sequentially in the same order. Maintain phase separation (decomposition → investigation → confirmation → hearing → grouping → drafting → approval → registration) as a work discipline, and do not mix in writes before approval
• Deliverable files (cases.json / investigation-<id>.json / issue-index.json / grouping-plan.json / drafts/) are created in the same way during degradation. To conserve context, treat the files as the source of truth for details of past phases and reread them when necessary
• Even during degradation, registration execution is performed in order, "one issue operation at a time" (observe the constraint of Rule 6 within yourself as well)
• Grouping decisions follow the rules of references/grouping-rules.md , and leave the basis for the decision in grouping-plan.json leave in

Reference documents

Details of each phase and topic are split under references/ . At execution time, refer to the relevant file.

• Orchestration detailed protocol (Phases 0–7): references/orchestration-protocol.md
  • Execution directory and deliverable file schema / parent's work and worker request contents for each phase / user dialogue scale design (batch confirmation, confidence triage, missing-information-driven hearing, plan-unit approval) / execution worker discipline
• Grouping rules: references/grouping-rules.md
  • Definition of the expected change area (touch set) / overlap determination and "merge if there is a possibility of interference" / blocking of transitive connections (handling of cross-cutting areas) / operation of cross-cutting markers (label source of truth + 【横断】 prefix) / existing issue matching rules
• Issue body format and rewriting procedure: references/issue-format.md
  • Templates for single cases and multiple cases / standard format for target areas / existing issue body rewriting (merging) procedure / recording of update history

Important constraints

• Do not write to GitHub until you obtain the user's explicit approval (approval of the Phase 7 registration plan). After approval, the only writes permitted are the following three types, and no other write operations (closing issues, posting comments, assigning, etc.) may be performed:
  • gh issue create(new registration)
  • For the approved merge destination, gh issue edit <番号> --body(merging by rewriting the body. For the procedure, see references/issue-format.md）
  • Label assignment (type label,scope:cross-cutting, pending-confirmation label needs-triage. If the latter two do not exist, gh label create is included.needs-triage is applied both to all new issues and to the merge destination into which the body was integrated, and functions as a review gate that engineers remove after confirming the content)
• Do not edit, create, or delete source code or configuration files (code investigation is read-only. Artifact files under the execution directory are exceptions)
• Do not propose solutions, implementation methods, or specification drafts on your own, and do not write them in issues (only proposals the reporter voluntarily stated are recorded separately as "the reporter's idea")
• Do not force answers to questions. Clearly state "unknown" for items you do not know
• Do not use technical terms or file paths in questions or confirmations to the user (the only exception is the "reference information for developers" section in the issue body)
• When summarizing or paraphrasing the user's statements, always confirm with "Is this understanding correct?" before writing it in the issue. Do not arbitrarily translate vague reports into specific content without confirmation
• In integration (body rewriting), do not delete or summarize the content already described in existing issues. Add cases while preserving all existing descriptions
• When the gh command cannot be used or is not authenticated: Do not stop with an error; present the registration plan (title and body) in a copyable form, and guide the user through the manual registration steps in plain language: "Open this project's page on GitHub → Issues tab at the top → green New issue button → paste and Submit"