Appropriate use
Use for new defects, support escalations, failed test results, production observations, or issues returning from engineering.
Scope and intent
A controlled workflow specification
This page defines the behaviour, controls, evidence, and outputs required from the skill. It does not claim that a language model can enforce security or correctness by wording alone.
Non-goals
Do not use to close reports automatically, assign blame, replace incident command, or declare root cause without evidence.
- 8
- versioned workflow phases
- 3
- explicit approval gates
- 6
- defined result states
- 8
- versioned output artifacts
Material changes to the source, environment, identity, approved actions, or expected behaviour invalidate dependent approvals and require revalidation.
Workflow
The 8 phases
Each phase has explicit inputs and outputs. Approval gates are hard stops bound to exact versions and hashes.
Phase 1: Issue snapshot Gate 1 · approve evidence set
Freeze the current issue revision, comments, attachments, environment details, linked releases, and current status before interpretation.
issue revision · reporter · timestamps · links · current owner
Phase 2: Evidence quality assessment
Check whether the issue contains an observable mismatch, sourced expectation, environment identity, reproduction detail, impact evidence, and privacy-safe attachments.
complete · partial · contradictory · stale · inaccessible
Phase 3: Failure-class analysis
Evaluate product defect, expected behaviour, requirement gap, environment failure, test-data failure, automation failure, third-party failure, duplicate candidate, security concern, and unknown.
candidate classes · supporting evidence · contradicting evidence
Phase 4: Scope and impact analysis
Estimate affected users, platforms, versions, tenants, data, permissions, recoverability, workaround, frequency, and customer visibility.
breadth · depth · permanence · recoverability · detectability
Phase 5: Severity and release-blocking assessment
Apply defined severity criteria separately from priority and scenario criticality. Record uncertainty and escalation triggers.
severity · priority recommendation · release blocking · confidence
Phase 6: Ownership and next-action mapping
Identify the team or role best positioned to investigate, the minimum next evidence, and whether the issue belongs in product backlog, incident flow, support follow-up, or test infrastructure.
owner · next action · due condition · escalation path
Phase 7: Human triage review Gate 2 · confirm triage
Present classification, severity rationale, duplicate candidates, unknowns, and proposed disposition for confirmation.
accepted class · accepted severity · owner · unresolved questions
Phase 8: Update issue and audit record Gate 3 · publish triage
Update the existing issue idempotently, preserve the previous state, link evidence, and record who approved the change.
status transition · comment · labels · owner · audit event
Approval contract
Every gate approves an exact decision object
An approval cannot be reused after its environment, source, action plan, or approved document changes.
| Gate | Decision | Required binding |
|---|---|---|
| 1 | Gate 1 · approve evidence set | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
| 2 | Gate 2 · confirm triage | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
| 3 | Gate 3 · publish triage | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
Result model
Defined states prevent vague conclusions
Attempt outcomes remain separate from these workflow results. Errors, cancellations, and invalid context are never silently converted into a pass.
PRODUCT DEFECT
Evidence supports a product behaviour mismatch.
EXPECTED BEHAVIOUR
The observed result matches the approved requirement or documented limitation.
ENVIRONMENT OR DATA ISSUE
The failure originates outside the product behaviour under review.
AUTOMATION ISSUE
The test implementation, fixture, selector, timing, or runner caused the result.
REQUIREMENT GAP
No authorised expectation exists or sources conflict.
UNKNOWN
Evidence cannot yet distinguish the leading classifications.
Evidence contract
Evidence must directly support the claim
Evidence has provenance, capture context, privacy classification, retention, and integrity metadata. A convenient artifact is not automatically sufficient proof.
| Claim | Primary evidence | Required validation |
|---|---|---|
| Issue history | Versioned issue snapshot | Status and comments can be traced to the triage time. |
| Symptom | Direct failure evidence | The claimed behaviour is visible or measurable. |
| Expectation | Approved source | The expected behaviour has an owner and revision. |
| Scope | Version, platform, tenant, and frequency data | Observed scope is distinguished from inferred scope. |
| Severity | Impact criteria mapping | Rationale addresses data, security, availability, workaround, and affected users. |
| Ownership | Component and dependency map | The proposed owner has a clear investigation boundary. |
Trust and safety
Controls that must be enforced outside the prompt
These controls belong in the runtime, connector permissions, sandbox, renderer, storage layer, and review process.
Runtime control
No automatic closure
Expected-behaviour and duplicate recommendations require human confirmation.
Runtime control
Severity consistency
A shared rubric prevents pressure or reporter seniority from changing severity silently.
Runtime control
Unknown is valid
The workflow may remain UNKNOWN instead of forcing a confident classification.
Runtime control
Security escalation
Potential security or privacy findings follow restricted handling and disclosure policy.
Runtime control
History preservation
Reclassification does not erase earlier evidence or decisions.
Runtime control
Conflict detection
Simultaneous issue edits trigger a refresh instead of overwriting newer changes.
Decision policy
Ordered outcomes, not averaged pass counts
The first applicable high-severity outcome takes precedence. A manual override is recorded separately and never rewrites the calculated result.
ESCALATE
Security, privacy, widespread outage, or data-integrity risk requires a specialist or incident path.
INVESTIGATE
Classification or scope remains materially uncertain.
ROUTE
The issue belongs to a known non-product owner or workflow.
ACCEPT PRODUCT DEFECT
Evidence supports backlog or release action as a product defect.
CLOSE WITH REASON
Human review confirms expected behaviour or a resolved duplicate.
Known limitations
Uncertainty and coverage limits remain visible
The workflow documents what it cannot prove and what further evidence would change confidence.
- Limit 1. Triage is a decision under uncertainty and may change as evidence improves.
- Limit 2. Severity is not the same as engineering effort or business priority.
- Limit 3. Multiple failures may share a symptom while having different causes.
- Limit 4. Customer impact can exceed the laboratory reproduction scope.
- Limit 5. A probable duplicate should remain open until a human confirms equivalence.
- Limit 6. Production security findings may need restricted records rather than normal issue comments.
Outputs
Versioned records for review and continuation
Human summaries are generated from validated structured records. They are not maintained as separate, drifting sources of truth.
triage-context.jsonVersioned output produced by the workflow.
evidence-assessment.mdVersioned output produced by the workflow.
classification-matrix.yamlVersioned output produced by the workflow.
impact-assessment.mdVersioned output produced by the workflow.
duplicate-candidates.mdVersioned output produced by the workflow.
triage-decision.jsonVersioned output produced by the workflow.
issue-update.mdVersioned output produced by the workflow.
triage-report.htmlVersioned output produced by the workflow.
artifacts/qa/bug-triage/<run-id>/ ├── triage-context.json ├── evidence-assessment.md ├── classification-matrix.yaml ├── impact-assessment.md ├── duplicate-candidates.md ├── triage-decision.json ├── issue-update.md └── triage-report.html
Example
Example request and controlled output
Input
Triage issue QA-4401. It fails only on webOS 6.0 for one display model, while another webOS 6.0 model works.
Output excerpt
Triage result: INVESTIGATE Leading classification: Product defect or model-specific firmware incompatibility. Current severity: Medium, confidence low. Why: The problem is reproducible on 55UL3J-MP but not 55UL3Q-E with the same content and player version. Next evidence: Firmware versions, browser engine details, network trace, and a same-screen source comparison.
Production readiness
Required before operational use
The written skill is only one layer. The repository, runtime, connectors, evidence storage, and publication path must implement these requirements.
- Required. Tool, filesystem, repository, command, secret, and network permissions are enforced outside the model.
- Required. Every source, environment, build, plan, and approval has a version or content hash.
- Required. Untrusted values are escaped, length-bounded, path-safe, and separated from executable instructions.
- Required. Attempt outcomes, scenario verdicts, workflow decisions, and publication status remain separate.
- Required. Raw evidence, publishable evidence, access control, retention, redaction, and deletion are defined.
- Required. Concurrent runs use unique IDs, locks, idempotency keys, and conflict-aware updates.
- Required. Material changes invalidate dependent approvals and outcomes.
- Required. The repository validator passes before the skill is considered production-ready.
In one line
/bug-triage
Reviews an incoming issue and determines what it most likely represents, how severe it is, who should own it, what evidence is missing, and what action should happen next.