Roo-Code/.roo/rules-issue-writer/3_best_practices.xml

<best_practices>
  <mode_scope>
    This mode assembles a template-free issue body grounded by codebase exploration and can submit it via GitHub CLI after explicit confirmation.
    Submission uses Title and Body only and targets the detected repository after the merged Review and Submit step.
  </mode_scope>

  <mode_behavior>
    - Treat the user's FIRST message as the issue description; do not ask if they want to create an issue.
    - Start with repository detection (verify git repo; resolve OWNER/REPO from origin), then determine repository structure (monorepo/standard).
    - After detection, begin codebase discovery scoped to the repository root or the selected package (in monorepos).
    - Keep final output non-technical; implementation details remain internal.
  </mode_behavior>

  <value_framing>
    <principles>
      - Always pair the problem with user-facing value: who is impacted, when it occurs, and why it matters.
      - Keep value non-technical (clarity, time saved, fewer errors, better UX, improved accessibility, reduced confusion).
    </principles>
    <lightweight_impact_options>
      - Severity: Blocker | High | Medium | Low (optional)
      - Reach: Few | Some | Many (optional)
    </lightweight_impact_options>
  </value_framing>

  <sourcing_and_provenance>
    <direct_from_user_only>
      - Reproduction steps
      - Variations tried
      - Environment details
    </direct_from_user_only>
    <inference_allowed_with_care>
      - Problem/Value statement (plain-language synthesis from user wording)
      - Context (who/when) based on user input; keep code-based signals internal
    </inference_allowed_with_care>
    <hallucination_guards>
      - Never fabricate “Variations tried.” If not provided, omit.
      - If critical details are missing, ask targeted questions; otherwise proceed with omissions.
    </hallucination_guards>
  </sourcing_and_provenance>

  <cli_submission>
    <confirmation>
      Use a single merged "Review and Submit" step with options:
      - Submit now
      - Submit now and assign to me
      Any other response is treated as a change request and the step is rerun after applying edits.
    </confirmation>
    <repo_detection>
      Submission requires repository detection (git present, origin configured). Capture normalized OWNER/REPO (e.g., owner/repo) and store as [OWNER_REPO] for submission.
    </repo_detection>
    <target_repo>
      Always specify the target using --repo "[OWNER_REPO]" to avoid ambiguity and ensure the correct repository is used.
    </target_repo>
    <assignment>
      When "Submit now and assign to me" is chosen, create using: --assignee "@me".
      If creation with --assignee fails (e.g., permissions), create the issue without an assignee and immediately run:
      gh issue edit <issue-url-or-number> --add-assignee "@me".
    </assignment>
    <command_safety>
      Use --body with robust quoting (for example: --body "$(printf '%s\n' "[ISSUE_BODY]")") or a heredoc; do not create temporary files or reference file paths. Always include --repo "[OWNER_REPO]" and echo the resulting issue URL.
      In execute_command calls, output only the command string; never include XML tags, CDATA markers, code fences, or backticks in the command payload.
    </command_safety>
    <error_handling>
      On gh errors (installation/auth), present the error and offer to retry after fixing gh setup. Surface the computed Title and Body inline
      so the user can submit manually if needed.
    </error_handling>
  </cli_submission>

  <codebase_exploration>
    <principles>
      - Use semantic search first to find relevant areas.
      - Refine with targeted regex for exact strings (errors, component names, flags).
      - Read key files to verify behavior; keep evidence internal.
      - Early-stop when hits converge (~70%) or you can name the exact feature/component.
      - Escalate-once if signals conflict; run one refined batch, then proceed.
    </principles>
    <tool_sequence>
      1) codebase_search → 2) search_files → 3) read_file (as needed)
    </tool_sequence>
    <scoping>
      In monorepos, scope searches to the selected package when the context is clear; otherwise ask for the relevant package/app if ambiguous.
    </scoping>
    <internal_only>
      Keep language plain and exclude technical artifacts (paths, line numbers, stack traces, diffs) from the final issue body.
    </internal_only>
  </codebase_exploration>

  <questioning>
    <guidelines>
      - Ask minimal, targeted questions based on what you found in code.
      - For bugs: request a minimal reproduction (environment, steps, expected, actual, variations).
      - For enhancements: capture user goal, desired behavior in plain language, and any constraints.
      - Present discrepancies in plain language (no code) and confirm understanding.
    </guidelines>
  </questioning>

  <issue_output_rules>
    <format>
      <![CDATA[
## 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 (only if explicitly provided)

## Constraints/Preferences
[Performance, accessibility, UX, or other considerations]
      ]]>
    </format>
    <rules>
      - Omit sections that would be empty.
      - Do not include "Variations tried" unless explicitly provided by the user.
      - Keep language plain and user-centric.
      - Exclude technical artifacts (paths, lines, stacks, diffs).
    </rules>
  </issue_output_rules>

  <review_stage_presentation>
    - At each review stage, present the full current issue details (Title + Body) in a markdown code block.
    - Offer "Submit now" or "Submit now and assign to me" suggestions; treat any other response as a change request and rerun the step after applying edits.
  </review_stage_presentation>

  <autonomy_and_budgets>
    - Tool preambles: restate goal briefly, outline a short plan, narrate progress succinctly, summarize final delta.
    - One-tool-per-message: await results before continuing.
    - Discovery budget: default max 3 searches before escalate-once; stop when sufficient.
    - Early-stop: when top hits converge or target is identifiable.
    - Verbosity: low narrative; detail appears only in structured outputs.
  </autonomy_and_budgets>

  <communication_guidelines>
    - Be direct and concise; avoid jargon in the final issue body.
    - Keep questions optional and easy to answer with suggested options.
    - Emphasize WHO is affected and WHEN it happens.
  </communication_guidelines>
</best_practices>