Roo-Code/.roo/rules-issue-writer/1_workflow.xml

<workflow>
  <mode_overview>
    This mode focuses solely on assembling a template-free GitHub issue prompt for an AI coding agent.
    It integrates codebase exploration to ground the prompt in reality while keeping the output non-technical.
    It also captures the user-facing value/impact (who is affected, how often, and why it matters) to support prioritization, all in plain language.
  </mode_overview>

  <iteration_policy>
    <principles>
      - Codebase exploration is iterative and may repeat as many times as needed based on user-agent back-and-forth.
      - Early-stop and escalate-once apply per iteration; when new info arrives, start a fresh iteration.
      - One-tool-per-message is respected; narrate succinct progress and update TODOs each iteration.
    </principles>
    <loop_triggers>
      - New details from the user (environment, steps, screenshots, constraints)
      - Clarifications that change scope or target component/feature
      - Discrepancies found between user claims and code
      - Reclassification between Bug and Enhancement
    </loop_triggers>
  </iteration_policy>

  <initialization>
    <notes>
      - Treat the user's FIRST message as the issue description; do not ask if they want to create an issue.
      - Begin immediately: initialize a focused TODO list and start repository detection before discovery.
      - CLI submission via gh happens only after the user confirms during the merged review/submit step.
    </notes>
    <update_todo_list>
      <todos>
      [ ] Detect repository context (OWNER/REPO, monorepo, roots)
      [ ] Perform targeted codebase discovery (iteration 1)
      [ ] Clarify missing details (repro or desired outcome)
      [ ] Classify type (Bug | Enhancement)
      [ ] Assemble Issue Body
      [ ] Review and submit (Submit now | Submit now and assign to me)
      </todos>
    </update_todo_list>
  </initialization>

  <steps>
    <step number="1">
      <name>Kickoff</name>
      <instructions>
        Rephrase the user's goal and outline a brief plan, then proceed without delay.
        Maintain low narrative verbosity; use structured outputs for details.
      </instructions>
    </step>

    <step number="2">
      <name>Detect Current Repository Information</name>
      <instructions>
        Verify we're in a Git repository and capture the GitHub remote for safe submission.

        1) Check if inside a git repository:
        <execute_command>
        <command>git rev-parse --is-inside-work-tree 2>/dev/null || echo "not-git-repo"</command>
        </execute_command>

        If the output is "not-git-repo", stop:
        <attempt_completion>
        <result>
        This mode must be run from within a GitHub repository. Navigate to a git repository and try again.
        </result>
        </attempt_completion>

        2) Get origin remote and normalize to OWNER/REPO:
        <execute_command>
        <command>git remote get-url origin 2>/dev/null | sed -E 's/.*[:/]([^/]+)\/([^/]+)(\.git)?$/\1\/\2/' | sed 's/\.git$//'</command>
        </execute_command>

        If no origin remote exists, stop:
        <attempt_completion>
        <result>
        No GitHub 'origin' remote found. Configure a GitHub remote and retry.
        </result>
        </attempt_completion>

        Record the normalized OWNER/REPO (e.g., owner/repo) as [OWNER_REPO] to pass via --repo during submission.
 
         3) Combined monorepo check and roots discovery (single command):
         <execute_command>
         <command>set -e; if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo "not-git-repo"; exit 0; fi; OWNER_REPO=$(git remote get-url origin 2>/dev/null | sed -E 's/.*[:/]([^/]+)\/([^/]+)(\.git)?$/\1\/\2/' | sed 's/\.git$//'); IS_MONO=false; [ -f package.json ] && grep -q '"workspaces"' package.json && IS_MONO=true; for f in lerna.json pnpm-workspace.yaml rush.json; do [ -f "$f" ] && IS_MONO=true; done; ROOTS="."; if [ "$IS_MONO" = true ]; then ROOTS=$(git ls-files -z | tr '\0' '\n' | grep -E '^(apps|packages|services|libs)/[^/]+/package\.json$' | sed -E 's#/package\.json$##' | sort -u | paste -sd, -); [ -z "$ROOTS" ] && ROOTS=$(find . -maxdepth 3 -name package.json -not -path "./node_modules/*" -print0 | xargs -0 -n1 dirname | grep -E '^(\.|\.\/(apps|packages|services|libs)\/[^/]+)$' | sort -u | paste -sd, -); fi; echo "OWNER_REPO=$OWNER_REPO"; echo "IS_MONOREPO=$IS_MONO"; echo "ROOTS=$ROOTS"</command>
         </execute_command>
 
         Interpretation:
         - If output contains OWNER_REPO, IS_MONOREPO, and ROOTS, record them and treat Step 3 as satisfied.
         - If output is "not-git-repo", stop as above.
         - If IS_MONOREPO=true but ROOTS is empty, perform Step 3 to determine roots manually.
 
         <update_todo_list>
           <todos>
           [x] Detect repository context (OWNER/REPO, monorepo, roots)
           [ ] Perform targeted codebase discovery (iteration N)
           [ ] Clarify missing details (repro or desired outcome)
           [ ] Classify type (Bug | Enhancement)
           [ ] Assemble Issue Body
           [ ] Review and submit (Submit now | Submit now and assign to me)
           </todos>
         </update_todo_list>
      </instructions>
    </step>

    <step number="3">
      <name>Determine Repository Structure (Monorepo/Standard)</name>
      <instructions>
        If Step 2's combined detection output includes IS_MONOREPO and ROOTS, mark this step complete and proceed to Step 4. Otherwise, use the manual process below.

        Identify whether this is a monorepo and record the search root(s).

        1) List top-level entries:
        <list_files>
        <path>.</path>
        <recursive>false</recursive>
        </list_files>

        2) Monorepo indicators:
        - package.json with "workspaces"
        - lerna.json, pnpm-workspace.yaml, rush.json
        - Top-level directories like apps/, packages/, services/, libs/

        If monorepo is detected:
        - Discover package roots by locating package.json files under these directories
        - Prefer scoping searches to the package most aligned with the user's description
        - Ask for package selection if ambiguous

        If standard repository:
        - Use repository root for searches

        <update_todo_list>
          <todos>
          [x] Detect repository context (OWNER/REPO, monorepo, roots)
          [-] Perform targeted codebase discovery (iteration N)
          [ ] Clarify missing details (repro or desired outcome)
          [ ] Classify type (Bug | Enhancement)
          [ ] Assemble Issue Body
          [ ] Review and submit (Submit now | Submit now and assign to me)
          </todos>
        </update_todo_list>
      </instructions>
    </step>

    <step number="4">
      <name>Codebase-Aware Context Discovery (Iterative)</name>
      <instructions>
        Purpose: Understand the context of the user's description by exploring the codebase. This step is repeatable.

        Discovery workflow (respect one-tool-per-message):
        1) Extract keywords, component names, error phrases, and concepts from the user's message or latest reply.
        2) Run semantic search:
        <codebase_search>
        <query>[Keywords from user's description or latest reply]</query>
        </codebase_search>

        3) Refine with targeted regex where helpful:
        <search_files>
        <path>.</path>
        <regex>[exact error strings|component names|feature flags]</regex>
        </search_files>

        4) Read key files for verification when necessary:
        <read_file>
        <path>[relevant file path from search hits]</path>
        </read_file>

        Guidance:
        - Early-stop per iteration when top hits converge (~70%) or you can name the exact feature/component involved.
        - Escalate-once per iteration if signals conflict: run one refined batch, then proceed.
        - Keep findings internal; do NOT include file paths, line numbers, stack traces, or diffs in the final prompt.

        Iteration rules:
        - After ANY new user input or clarification, return to this step with updated keywords.
        - Update internal notes and TODOs to reflect the current iteration (e.g., iteration 2, 3, ...).

        <update_todo_list>
          <todos>
          [x] Detect repository context (OWNER/REPO, monorepo, roots)
          [-] Perform targeted codebase discovery (iteration N)
          [ ] Clarify missing details (repro or desired outcome)
          [ ] Classify type (Bug | Enhancement)
          [ ] Assemble Issue Body
          [ ] Review and submit (Submit now | Submit now and assign to me)
          </todos>
        </update_todo_list>
      </instructions>
    </step>

    <step number="5">
      <name>Clarify Missing Details (Guided by Findings)</name>
      <instructions>
        Ask minimal, targeted questions grounded by what you found in code.

        For Bug reports:
        <ask_followup_question>
        <question>I’m verifying the behavior around [feature/component inferred from code]. Could you provide a minimal reproduction and quick impact details?</question>
        <follow_up>
        <suggest>Repro format: 1) Environment/setup 2) Steps 3) Expected 4) Actual 5) Variations (only if you tried them)</suggest>
        <suggest>Impact: Who is affected and how often does this happen?</suggest>
        <suggest>Cost: Approximate time or outcome cost per occurrence (optional)</suggest>
        </follow_up>
        </ask_followup_question>

        For Enhancements:
        <ask_followup_question>
        <question>To capture the improvement well, what is the user goal and value in plain language?</question>
        <follow_up>
        <suggest>State the user goal and when it occurs</suggest>
        <suggest>Describe the desired behavior conceptually (no code)</suggest>
        <suggest>Value: Who benefits and what improves (speed, clarity, fewer errors, conversions)?</suggest>
        </follow_up>
        </ask_followup_question>

        Discrepancies:
        - If you found contradictions between description and code, present concrete, plain-language examples (no code) and ask for confirmation.

        Loop-back:
        - After receiving any answer, return to Step 4 (Discovery) with the new information and repeat as needed.

        <update_todo_list>
          <todos>
          [x] Detect repository context (OWNER/REPO, monorepo, roots)
          [x] Perform targeted codebase discovery (iteration N)
          [-] Clarify missing details (repro or desired outcome)
          [ ] Classify type (Bug | Enhancement)
          [ ] Assemble Issue Body
          [ ] Review and submit (Submit now | Submit now and assign to me)
          </todos>
        </update_todo_list>
      </instructions>
    </step>

    <step number="6">
      <name>Classify Type (Provisional and Repeatable)</name>
      <instructions>
        Use the user's description plus verified findings to choose:
        - Bug indicators: matched error strings; broken behavior in existing features; regression indicators.
        - Enhancement indicators: capability absent; extension of existing feature; workflow improvement.
        - Impact snapshot (optional): Severity (Blocker/High/Medium/Low) and Reach (Few/Some/Many). If uncertain, omit and proceed.

        Confirm with the user if uncertain:
        <ask_followup_question>
        <question>Based on the behavior around [feature/component], should we frame this as a Bug or an Enhancement?</question>
        <follow_up>
        <suggest>Bug Report</suggest>
        <suggest>Enhancement</suggest>
        </follow_up>
        </ask_followup_question>

        Reclassification:
        - If later evidence or user info changes the type, reclassify and loop back to Step 4 for a fresh discovery iteration.

        <update_todo_list>
          <todos>
          [x] Detect repository context (OWNER/REPO, monorepo, roots)
          [x] Perform targeted codebase discovery (iteration N)
          [x] Clarify missing details (repro or desired outcome)
          [-] Classify type (Bug | Enhancement)
          [ ] Assemble Issue Body
          [ ] Review and submit (Submit now | Submit now and assign to me)
          </todos>
        </update_todo_list>
      </instructions>
    </step>

    <step number="7">
      <name>Assemble Issue Body</name>
      <instructions>
        Build a concise, non-technical issue body. Omit empty sections entirely.

        Format:
        ```
        ## Type
        Bug | Enhancement

        ## Problem / Value
        [One or two sentences that capture the problem and why it matters in plain language]

        ## Context
        [Who is affected and when it happens]
        [Enhancement: desired behavior conceptually, in the user's words]
        [Bug: current observed behavior in plain language]

        ## Reproduction (Bug only, if available)
        1) Steps (each action/command)
        2) Expected result
        3) Actual result
        4) Variations tried (include only if the user explicitly provided them)

        ## Constraints/Preferences
        [Performance, accessibility, UX, or other considerations]
        ```

        Rules:
        - Keep non-technical; do NOT include code paths, line numbers, stack traces, or diffs.
        - Ground the wording in verified behavior, but keep implementation details internal.
        - Sourcing: Do not infer or fabricate reproduction details or “Variations tried.” Include them only if explicitly provided by the user; otherwise omit the line.
        - Quoting fidelity: If the user lists “Variations tried,” include them faithfully (verbatim or clearly paraphrased without adding new items).
        - Value framing: Ensure the “Problem / Value” explains why it matters (impact on users or outcomes) in plain language.
        - Title: Produce a concise Title (≤ 80 chars) prefixed with [BUG] or [ENHANCEMENT]; when helpful, append a brief value phrase in parentheses, e.g., “(blocks new runs)”.

        Iteration note:
        - If new info arrives after drafting, loop back to Step 4, then update this draft accordingly.

        <update_todo_list>
          <todos>
          [x] Detect repository context (OWNER/REPO, monorepo, roots)
          [x] Perform targeted codebase discovery (iteration N)
          [x] Clarify missing details (repro or desired outcome)
          [x] Classify type (Bug | Enhancement)
          [-] Assemble Issue Body
          [ ] Review and submit (Submit now | Submit now and assign to me)
          </todos>
        </update_todo_list>
      </instructions>
    </step>

    <step number="8">
      <name>Review and Submit (Single-Step)</name>
      <instructions>
        Present the full current issue details in a code block. Offer two submission options; any other response is treated as a change request.

        <ask_followup_question>
        <question>Review the current issue details. Select one of the options below or specify any changes or other workflow you would like me to perform:

```md
Title: [ISSUE_TITLE]

[ISSUE_BODY]
```</question>
        <follow_up>
        <suggest>Submit now</suggest>
        <suggest>Submit now and assign to me</suggest>
        </follow_up>
        </ask_followup_question>

        Responses:
        - If "Submit now":
          Prepare:
            - Title: derive from Summary (≤ 80 chars, plain language)
            - Body: the finalized issue body

          Execute:
          <execute_command>
          <command>gh issue create --repo "[OWNER_REPO]" --title "[ISSUE_TITLE]" --body "$(printf '%s\n' "[ISSUE_BODY]")"</command>
          </execute_command>

        - If "Submit now and assign to me":
          Execute (assignment at creation; falls back to edit if needed):
          <execute_command>
          <command>ISSUE_URL=$(gh issue create --repo "[OWNER_REPO]" --title "[ISSUE_TITLE]" --body "$(printf '%s\n' "[ISSUE_BODY]")" --assignee "@me") || true; if [ -z "$ISSUE_URL" ]; then ISSUE_URL=$(gh issue create --repo "[OWNER_REPO]" --title "[ISSUE_TITLE]" --body "$(printf '%s\n' "[ISSUE_BODY]")"); gh issue edit "$ISSUE_URL" --add-assignee "@me"; fi; echo "$ISSUE_URL"</command>
          </execute_command>

        - Any other response:
          - Collect requested edits and apply them
          - Loop back to Step 4 (Discovery) if new information affects context
          - Re-assemble in Step 7
          - Rerun this step and present the updated issue details

        On success: Capture the created issue URL from stdout and complete:
        <attempt_completion>
        <result>
        Created issue: [URL]
        </result>
        </attempt_completion>

        On failure: Present the error succinctly and offer to retry after fixing gh setup (installation/auth). Provide the computed Title and Body inline so the user can submit manually if needed.

        <update_todo_list>
          <todos>
          [x] Detect repository context (OWNER/REPO, monorepo, roots)
          [x] Perform targeted codebase discovery (iteration N)
          [x] Clarify missing details (repro or desired outcome)
          [x] Classify type (Bug | Enhancement)
          [x] Assemble Issue Body
          [x] Review and submit (Submit now | Submit now and assign to me)
          </todos>
        </update_todo_list>
      </instructions>
    </step>
  </steps>

  <completion_criteria>
    <criterion>Repository detection (git repo present and origin remote configured) is performed before any submission.</criterion>
    <criterion>Issue is submitted via gh after choosing "Submit now" or "Submit now and assign to me", and the created issue URL is returned.</criterion>
    <criterion>When "Submit now and assign to me" is chosen, the issue is assigned to the current GitHub user using --assignee "@me" (or gh issue edit fallback).</criterion>
    <criterion>Submission uses Title and Body only and specifies --repo [OWNER_REPO] discovered in Step 2; no temporary files or file paths are used.</criterion>
    <criterion>Language is plain and user-centric; no technical artifacts included in the issue body.</criterion>
    <criterion>Content grounded by repeated codebase exploration cycles as needed.</criterion>
    <criterion>Early-stop/escalate-once applied per iteration; unlimited iterations across the conversation.</criterion>
    <criterion>The merged step offers "Submit now" or "Submit now and assign to me"; any other response is treated as a change request and the step is shown again with the full current issue details.</criterion>
  </completion_criteria>
</workflow>