Kiro Bug Report

If the runtime allows local command execution, use the helper script from the global skill directory to gather the installed Kiro version and OS details before asking the user to type them manually.

Do not assume the current working directory is the skill folder. Resolve the script path explicitly, for example:

• python3 ~/.kiro/skills/kiro-bug-report/scripts/collect_kiro_env.py --markdown
• or the same path expanded to the user's home directory

Phase 1. Troubleshoot first

Start with the lightest useful troubleshooting step before moving into formal reporting.

Goal:

• rule out known FAQ cases
• identify whether the issue is temporary, local, or already resolved
• avoid escalating issues that can be quickly verified or self-resolved

If the issue appears resolved during troubleshooting:

• summarize what fixed it
• note any remaining uncertainty
• do not force a bug report unless the user still wants one

If the issue remains unresolved, continue to classification and reporting preparation.

During troubleshooting, suggest a short search pack the user can try before escalating:

• explain the search suggestion in the user's language
• provide the actual search keywords or short queries in English by default
• keep them specific to the observed symptom, feature area, and error text
• prefer search terms that are likely to match existing Discord posts, GitHub Issues, or troubleshooting docs
• mix narrow and broad search styles instead of using only one exact phrase

Build the search pack with these heuristics:

• one exact symptom query close to the user's wording
• one broader symptom query that removes extra words such as the product name when the context already makes it obvious
• one alternate phrasing that swaps verbs such as replying, responding, stuck, keep, or repeats
• when useful, one recency-style query that reflects how users describe fresh regressions, such as this keeps happening, recent builds, or latest version
• avoid overly polished full-sentence searches if a shorter phrase is more likely to match community posts
• if an exact query finds nothing, immediately suggest 2 to 3 shorter fallback variants

Only switch the search keywords away from English if the user explicitly asks for localized search terms too.

2. Classify the issue

Start by deciding which bucket fits best:

• Bug: clearly broken or incorrect behavior
• Setup Issue: install, configuration, onboarding, or environment problems
• MCP Issue: schema, tool registration, integration, or tool behavior problems
• Steering or Specs Issue: behavior shaped by steering/spec files or related workflows
• Platform Issue: macOS, Windows, or Linux specific behavior
• Account Issue: authentication or billing
• Feedback: product suggestion or UX complaint
• Usage Question: the user is unsure how Kiro is supposed to work

Do not guess a root cause. If the category is uncertain, say so and choose the closest working label.

Phase 2. Decide whether to escalate

Escalate only when at least one of these is true:

• the issue remains unresolved after reasonable troubleshooting
• the issue is reproducible or likely reproducible
• the issue blocks normal usage or causes significant confusion
• the issue looks like a product defect rather than a one-off usage mistake
• the user explicitly wants to report it anyway

If escalation is not justified yet:

• explain what to try next in the user's language
• suggest English search keywords the user can use immediately, while explaining their purpose in the user's language
• give actionable closure instead of ending with only "no need to report"
• include:
  • Recommended Next Action
  • Prevention Tips
  • When to Report
• stop at troubleshooting guidance instead of generating a full report

3. Collect the minimum missing facts

Ask short follow-up questions only for the information still needed to produce a useful report:

• What happened?
• What did you expect to happen?
• How can it be reproduced?
• Is it reproducible every time?
• What environment are you using?
• What is the exact error message?
• What evidence already exists: logs, screenshots, or DevTools findings?

When available, run python3 ~/.kiro/skills/kiro-bug-report/scripts/collect_kiro_env.py --markdown and paste its output directly into the final report. Use the default JSON output only when structured data is more useful than paste-ready text.

If the helper script cannot be found or executed, fall back to asking the user for Kiro version, OS, and architecture instead of failing the workflow.

If the user has limited information, do not block. Produce a draft anyway and list the missing items clearly.

During this information-gathering stage, keep all questions and explanations in the user's language unless the user explicitly asks to switch languages.

4. Check known troubleshooting patterns

Before routing the issue, compare it against the known quick-check cases in references/routing-notes.md.

If the issue matches a known pattern:

• tell the user which quick checks to try first
• keep the guidance short
• still prepare a report draft if the user wants to continue

If more evidence is needed, suggest Help > Toggle developer tools.

Use the troubleshooting templates in references/troubleshooting-templates.md to choose the best Troubleshooting Attempted section:

• use the general template for any issue with limited context
• use the unexpected error template when the report matches the known FAQ pattern
• use the MCP template for schema, tool registration, or integration issues

Phase 3. Prepare the report

Only enter this phase when the issue should be escalated.

If the issue does not need escalation, do not generate a formal Discord or GitHub report. Instead, give a compact troubleshooting outcome in the user's language with:

• what likely happened
• what the user should do now
• how to reduce the chance of the issue recurring
• what signal would make the issue worth reporting later

5. Draft the report

Always write the final external-facing deliverable in English.

Before the final report, you may briefly explain what you are doing or what is still missing in the user's language.

When useful, include a short Suggested Search Keywords section before the final report so the user can quickly check for similar reports before posting. The section label or explanation may follow the user's language, but the keyword list itself should default to English.

If the first search pack is too narrow, provide a second-pass fallback pack with shorter and looser variants.

Use references/discord-template.md when the route is Discord.

Use references/github-template.md when the route is GitHub Issues.

Use references/non-escalation-templates.md for the compact closure format when the issue does not need escalation.

Replace the placeholder Troubleshooting Attempted section in those templates with the most relevant checklist from references/troubleshooting-templates.md. Keep only the lines that actually fit the case.

When the route is Discord:

• fill Discord Post Title
• fill Discord Post Body
• treat Recommended Tags as a manual suggestion list for the user to apply in the Discord UI
• include optional search keywords when they may help the user check duplicates faster
• keep Recommended Tags outside the copy-ready Discord title and body blocks
• GitHub title and body may be omitted if not useful

When the route is GitHub Issues:

• fill GitHub Issue Title
• fill GitHub Issue Body
• keep title and body as separate copy-ready blocks
• align the issue body with the current Kiro GitHub issue field style from references/github-template.md
• include direct links the user can click for the Kiro issue tracker and new issue entry point
• choose the bug or feature template from references/github-template.md based on issue type
• keep Discord title and body optional unless the user also wants a Discord cross-post

6. Route the issue

Use the routing notes in references/routing-notes.md.

Default routing rules:

• Usage Question or Setup Issue -> Discord
• known troubleshooting case -> Troubleshooting First, then Discord if still reproducible
• clear reproducible product bug -> GitHub Issues after duplicate check; Discord is also acceptable when the user wants fast triage
• Account Issue -> official account-related channel
• MCP Issue, Steering or Specs Issue, or platform-specific behavior -> Discord with focused tags

When recommending Discord:

• include only the most relevant tags
• explain the route in one sentence
• remind the user to search for duplicates before posting
• do not assume tags can be auto-applied; present them as recommended manual tags unless the product clearly supports automatic tagging

When recommending GitHub Issues:

• advise checking existing issues first
• provide a polished report title and body that are easy to paste

Guardrails

• Do not over-question the user.
• Do not skip troubleshooting when a low-cost check is clearly available.
• Do not invent version numbers, logs, or reproduction steps.
• Do not label every problem as a bug.
• Do not write a long essay when a concise report is enough.
• Prefer specific titles that mention the failing area, trigger, and impact.
• If severity is useful, describe impact in plain language instead of inventing an internal priority scale.
• Keep the interaction language aligned with the user's language; switch to English only for the final report unless the user requests otherwise.
• When suggesting search terms, keep the explanation in the user's language and default the actual keyword list to English unless the user asks otherwise.
• When escalation is not needed, still leave the user with concrete next steps, prevention advice, and a clear future reporting threshold.