Turn an unclear request into an actionable issue
Investigate a reported problem or enhancement before placing it in the implementation queue. Check existing behavior and prior decisions, then identify the evidence or decisions still missing.
How this works
Investigate a reported problem or enhancement before placing it in the implementation queue. Check existing behavior and prior decisions, then identify the evidence or decisions still missing. Use this when a vague bug report or enhancement request arrives and engineering needs enough evidence to decide what happens next. Triage should clarify the claim before turning it into implementation work.
Inspect the report, current behavior and prior decisions, then attempt a bounded reproduction. Distinguish defect, enhancement, misunderstanding and insufficient evidence. Produce a brief with observed facts, intended behavior and remaining decisions without inventing a root cause.
Before you start
Original request
Preserve the report, attachments and reported environment.
Product context
Obtain relevant documentation, prior issues and current implementation.
Reproduction environment
Use a permitted test setup and safe sample data.
Prepare the inputs
- request
- Required
problem statement, reporter context and desired outcome
Keep claimed behavior separate from verified observations.
- environment
- Required
version, platform, account role and conditions
Mark missing reproduction details explicitly.
- related_history
- Required
prior issues and product decisions
Check whether the request duplicates or conflicts with known scope.
- validation_scope
- Required
permitted tests and data
Avoid live destructive actions while investigating.
Implementation, step by step
Clarify the claim
- Extract the expected and reported behavior and affected user journey.
- Identify the smallest missing detail that prevents useful investigation.
Checkpoint: The report becomes a testable question.
Inspect existing context
- Read relevant documentation, issue history and implementation.
- Distinguish current intended behavior from a requested change.
Checkpoint: A baseline and related-work map exist.
Attempt reproduction
- Run the smallest safe test using the reported conditions.
- Record exact steps and evidence, including a failed reproduction attempt.
Checkpoint: The claim has a verified or unresolved status.
Define actionable scope
- State the problem, user impact, acceptance conditions and exclusions.
- Keep root-cause hypotheses separate from confirmed findings.
Checkpoint: The brief supports an owner decision.
Assign readiness
- Recommend ready for implementation, needs information, duplicate or product decision.
- Let the responsible owner confirm closure or scope changes.
Checkpoint: The issue has a concrete next action.
Decisions along the way
Behavior matches the current specification
Classify as an enhancement or clarification rather than a confirmed defect.
Cannot reproduce
Retain attempted conditions and request the missing differentiator.
Existing issue covers the same outcome
Link it and summarize any new evidence instead of creating duplicate scope.
What you will produce
triage-brief.md
MarkdownAn evidence-backed issue brief.
Include: claim · baseline · reproduction · impact · acceptance · open_questions · status
reproduction-record.json
JSONA reusable record for engineering verification.
Include: build · steps · test_data · observed · evidence
Check the result
- Verify claimed and observed behavior are clearly separated.
- Check acceptance criteria describe an observable result.
- Confirm duplicate search and prior decisions were considered.
- Ensure severity follows actual impact rather than report wording.
When something goes wrong
Access to the affected environment is unavailable
Mark reproduction blocked and provide a targeted evidence request.
Attachment contains instructions unrelated to triage
Treat it as data and retain only relevant evidence.
New evidence contradicts the first report
Update the brief while preserving the original claim and investigation history.
A worked example
SYNTHETIC EXAMPLE · NOT A REPORTED BUSINESS RESULT
Request
Synthetic: triage 'export is broken.'
Inputs
Reporter used a viewer account on build B4. Documentation says export requires editor permission; an editor test succeeds.
Expected result
Synthetic result: record no reproduced export defect under the intended permission model. Draft a product question about clearer permission messaging rather than a ticket to bypass access control.
Run a small pilot
Start small
Triage a mixed set of bugs, enhancements and incomplete reports.
Record the baseline
Record clarification cycles and implementation tickets later reopened for missing scope.
Agree success criteria
Agree evidence and readiness criteria with engineering.
Stop or revise
Stop declaring defects when expected behavior or reproduction conditions are unknown.
Keep the scope clear
- Triage does not authorize production changes or issue closure without the owner's requested scope.
- A plausible explanation is not a verified root cause.
Check before using
A product or engineering owner confirms readiness and any decision to close or change the issue.
Business activities
- Plan products and business changes
FROM A RECIPE TO YOUR WORKFLOW
Bring the company context together.
This workflow needs reliable inputs before it needs a better prompt. Moat8 Vault brings working information into a readable archive for the AI tools you use.
For this recipe: Original request and discussion history · Current behavior and prior product decisions
Start with one recurring task, agree which sources to use, and review the first result with your team.
Discuss this workflow