A gap between what a product was intended to do and what it actually does, tracked so the right team can close it.
A bug is a defect in a product where behaviour diverges from what was intended. It is the gap between the specificationSpecificationFoundationsA canonical open standard or specification that primitives and products conform toView reference → in someone's head (or in writing) and what the running system actually does.
The term is older than computing. Thomas Edison used "bug" for technical faults in his inventions; an 1878 letter refers to "'Bugs', as such little faults and difficulties are called". The famous 1947 incidentIncidentDevOps & PlatformA production incidentView reference →, in which a moth was found taped into the log book of Harvard's Mark II relay computer with the note "first actual case of a bug being found", is real, and Grace Hopper's team helped popularise the word in computing. The historian Fred Shapiro has shown the moth was a joke playing on an already-current term, not the origin of it.
What changed over the following decades was not the word but the rigour around it. The IEEE eventually separated the vocabulary: a fault is the latent flaw in the code, an error is the incorrect internal state it produces, and a failure is the observable wrong behaviour a user sees. "Bug" in common usage spans all three, which is why disciplined teams attach a severity and a reproduction path to pin down which they mean.
The economics of bugs drove the next shift. Studies popularised through Barry Boehm's work argued that defects grow more expensive to fix the later they are caught, which pushed testing earlier (the "shift left" movement) and made the goal preventing bugs at the point of writing rather than only catching them at the end.
Copeland's catalogue of test-design techniques shows why a precise reproduction path is worth recording: different techniques expose different classes of defect. Equivalence class testing groups inputs that should be treated identically; boundary value testing probes the edges of those ranges, where Copeland notes many defects hide; decisionDecisionStrategyA recorded decision with context, rationale, and consequencesView reference →-table and state-transition testing each target a distinct kind of scenario — combinations of business rules in one case, sequences of states and events in the other. Read against that catalogue, a bug's repro is more than an aid to the fixer: by naming the exact inputs and path that fail, it locates the defect within one of these classes, which points at the kind of test that should guard against its return.
A user reports that exporting a report as PDF produces a blank file. The team files a bug with a severity of high (data loss, no workaround) and a clear repro: export any report over 50 pages on the web app, in Safari, and the file is empty. The bug points at the export featureFeatureProduct SpecificationA product capability or featureView reference → it affects, which scopes the investigationInvestigationEngineeringAn investigation into an issue or incidentView reference → to one code path rather than the whole app.
A fix lands and the patch ships as releaseReleaseProduct SpecificationA shipped version of the productView reference → 3.1.2, the patch bump signalling a backward-compatible correction. The bug is marked resolved, and a regression testRegression TestQuality AssuranceA regression testView reference → is added so the same break cannot return silently. Because the bug recorded its repro and its severity up front, the team could triage it against other work honestly, and the link to the affected feature meant the right engineer picked it up without a hunt.
In the Unified Product Graph, bugbug_affects_featurebug_affects_service
Worked example: Trellis
A defect where a previewed change did not match what actually happened to the records is a critical bug for Trellis, a direct threatThreatSecurityA specific security threatView reference → to the trust wedge the featureFeatureProduct SpecificationA product capability or featureView reference → was built to establish. Because Safe Change's promise is that the preview is exact, this class of bug would convert a director's confidence into distrust and undermine the feature areaFeature AreaProduct SpecificationA grouping of related featuresView reference →'s entire rationale.
Severe Struggles to accomplish goal
Urgent Blocking progress or time-critical; must be addressed immediately.
Type-specific fields on BaseNode
bug_severityassessmentImpact severity (UPGAssessment on the `severity_5` scale). Independent of priority (which governs when it gets fixed). Migrated from the inline `critical|major|minor|trivial` enum (UPG-579 Option C): map `critical` -> 5, `major` -> 4, `minor` -> 2, `trivial` -> 1; carry the old word in `label`.
steps_to_reproducestringStep-by-step reproduction
environmentstringObserved environment (e.g. "prod", "staging", "iOS 17.4")
priorityenumUrgency relative to other work. Independent of `bug_severity` (a critical bug can have low priority if rare).
assigneestringAssigned person. Promote to a `node_owned_by_person` edge if ownership must be queryable.
due_datestringISO date due. Often tied to a release gate or SLA.
labelsstring[]Free-form classification tags. Applied uniformly across work item types.
workflow_statestringThe source tool's raw custom workflow state, verbatim and opaque (e.g. "In Review", "QA", "Needs Triage"). Non-canonical and never reasoned over: it exists to round-trip an import losslessly. Map it onto a canonical bucket with `workflow_state_category`; canonical `status` stays the sole reasoning axis.
workflow_state_categorystringCanonical bucket the raw `workflow_state` maps onto for reasoning (a source "In Review" and "QA" might both map to a verification phase). Optional companion to `workflow_state`: it lets a graph reason over an imported custom workflow without promoting the raw label to `status`.
idstringrequiredUnique identifier (UUID)
typeNodeTyperequiredDiscriminator for the entity type
titlestringrequiredDisplay name
descriptionstringOptional detailed description
statusstringLifecycle status
tagsstring[]Freeform tags for filtering
6 phases, initial: open · template: INCIDENT
12 edge types connected to this entity.
bug_affects_featureroot_cause_causes_buginvestigation_revealed_bugfix_resolved_bugbug_affects_servicesupport_ticket_reports_bugbug_observed_in_releaseregression_test_addresses_bugtest_result_reports_bug