Appropriate use
Use after a potential product issue has been observed and enough evidence exists to support triage.
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 convert every inconclusive result into a bug, assign blame, guess root cause, or expose secrets and customer data.
- 8
- versioned workflow phases
- 3
- explicit approval gates
- 5
- defined result states
- 9
- 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: Observation intake Gate 1 · approve intake
Capture the original observation, reporter wording, timestamps, environment, build, role, tenant, affected object, and existing evidence without rewriting uncertainty.
original statement · first evidence · reporter · time · environment
Phase 2: Environment and build verification
Confirm deployment identity, device or browser, OS, player version, configuration, flags, network, account state, and whether the issue occurred in production or a test environment.
artifact digest · source commits · platform · configuration · role
Phase 3: Reproduction design
Create the shortest controlled reproduction that preserves necessary preconditions and separates setup from the failing action.
preconditions · minimal steps · expected result · actual result · cleanup
Phase 4: Reproduction attempts
Attempt reproduction without retrying until success. Record every attempt, data variation, timing, and environment difference.
attempt outcomes · frequency · first failure retained · non-reproducible evidence
Phase 5: Classification and impact
Classify the issue type, affected users and platforms, frequency, recoverability, data or security impact, workaround, and confidence. Keep severity separate from scenario priority.
category · severity · release blocking · scope · confidence
Phase 6: Duplicate candidate review Gate 2 · confirm duplicate decision
Search existing issues by symptom, component, platform, error fingerprint, and root-cause clues. Present candidates for human decision rather than auto-closing the report.
candidate IDs · similarity · differences · status
Phase 7: Report drafting
Write a concise title, verified environment, preconditions, steps, expected and actual results, frequency, impact, evidence, logs, and notes. State hypotheses as hypotheses.
plain language · stable links · redacted evidence · no unsupported root cause
Phase 8: Review and publication Gate 3 · publish defect
Review accuracy, privacy, severity, ownership, and linked evidence. Publish idempotently and preserve the local report revision.
approver · report hash · ticket ID · publication status
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 intake | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
| 2 | Gate 2 · confirm duplicate decision | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
| 3 | Gate 3 · publish defect | 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.
CONFIRMED DEFECT
Controlled evidence demonstrates product behaviour that contradicts an approved expectation.
PROBABLE DEFECT
Evidence is strong but reproduction, scope, or expectation has limited uncertainty.
NOT A PRODUCT DEFECT
The behaviour is expected or belongs to environment, data, automation, or third-party failure.
INSUFFICIENT EVIDENCE
The observation cannot yet support a responsible defect report.
DUPLICATE CANDIDATE
An existing issue may represent the same problem and requires a human decision.
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 |
|---|---|---|
| Original failure | Screenshot, video, trace, log, or customer evidence | Source, time, platform, and privacy status are recorded. |
| Reproduction | Attempt ledger | All attempts and variations remain visible. |
| Expected result | Requirement, design, contract, or authorised decision | Expectation is sourced rather than inferred from preference. |
| Actual result | Direct assertion-specific evidence | The evidence supports the exact claimed mismatch. |
| Impact | Affected-user and recovery analysis | Severity rationale is separate from probability and priority. |
| Duplicate review | Candidate comparison | Similarity and meaningful differences are stated. |
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 root-cause invention
Code clues may be listed as hypotheses but never presented as confirmed cause without evidence.
Runtime control
Privacy-first evidence
Secrets and personal data are filtered before storage and publication.
Runtime control
Severity discipline
Severity uses defined impact criteria; urgency and stakeholder pressure do not silently change it.
Runtime control
Attempt transparency
Failed, passed, aborted, and environment-error attempts are all retained.
Runtime control
Duplicate safety
Automated similarity cannot suppress a new issue without review.
Runtime control
Publication idempotency
Retries update the same draft or issue rather than creating duplicates.
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.
INSUFFICIENT EVIDENCE
The report cannot responsibly claim a product defect.
NOT A PRODUCT DEFECT
Evidence points to expected behaviour or another failure class.
PROBABLE DEFECT
A report may be published with explicit uncertainty and follow-up.
CONFIRMED DEFECT
Evidence supports publication as a product defect.
Known limitations
Uncertainty and coverage limits remain visible
The workflow documents what it cannot prove and what further evidence would change confidence.
- Limit 1. A defect may be real even when immediate reproduction fails.
- Limit 2. Customer evidence may be incomplete or privacy-sensitive and should not be treated as controlled execution.
- Limit 3. Severity can change as scope becomes clearer.
- Limit 4. Similar symptoms can have different causes across platforms.
- Limit 5. Logs may contain baseline noise and require versioned fingerprints.
- Limit 6. Publication systems may truncate large evidence; preserve a durable local bundle.
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.
bug-context.jsonVersioned output produced by the workflow.
original-observation.mdVersioned output produced by the workflow.
reproduction-plan.mdVersioned output produced by the workflow.
attempt-ledger.jsonlVersioned output produced by the workflow.
evidence-manifest.jsonVersioned output produced by the workflow.
duplicate-review.mdVersioned output produced by the workflow.
bug-report.mdVersioned output produced by the workflow.
publication-record.jsonVersioned output produced by the workflow.
bug-report.htmlVersioned output produced by the workflow.
artifacts/qa/bug-report/<run-id>/ ├── bug-context.json ├── original-observation.md ├── reproduction-plan.md ├── attempt-ledger.jsonl ├── evidence-manifest.json ├── duplicate-review.md ├── bug-report.md ├── publication-record.json └── bug-report.html
Example
Example request and controlled output
Input
Create a defect report for the player showing Ethernet as Active after switching back to Wi-Fi. I have before and after screenshots and reproduced it twice.
Output excerpt
Classification: CONFIRMED DEFECT Title: Network status remains “Ethernet” after the active connection changes to Wi-Fi Frequency: 2 of 2 controlled attempts Expected: Device Information shows the interface currently used by the player. Actual: Content reconnects through Wi-Fi and the IP address changes, but Active remains “Ethernet”. Evidence: Before and after screenshots, network request log, and attempt ledger attached.
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-report
Converts an observed problem into a precise, reproducible, environment-bound defect report without overstating cause, severity, or scope.