Building, Architecture & Workflows
The language of turning intent into systems: specs, scope, implementation, architecture, agent workflows, review loops, Git, testing, delivery, and the machinery that decides when work is actually done.
105 terms
Requirement
Something the system must do or a condition it must satisfy.
A requirement describes expected behavior, capability, quality, constraint, or outcome.
The system must preserve the original message timestamp.
Spec, acceptance criteria
A requirement states what must be true. It does not necessarily explain how to implement it.
Specification — Spec
A written description of what should be built.
A specification may define goals, behavior, data shapes, constraints, failure cases, interfaces, acceptance criteria, and out-of-scope work.
A document describing how a memory-capture tool should validate and store entries.
Plan, requirement, documentation
A spec describes the intended result. A plan describes how the builder intends to reach it.
Scope
The boundary of what work is included and excluded.
Scope defines the responsibilities, features, files, systems, and outcomes a task covers.
This change updates the capture adapter but does not redesign the storage layer.
Goal, requirement
A good scope includes explicit exclusions, not only a list of requested features.
Out of Scope
Work deliberately excluded from the current task.
Out-of-scope items are documented so the implementation does not expand silently or solve adjacent problems without approval.
Migrating historical records is out of scope for this patch.
Blocked work
Out of scope does not mean unimportant. It means not part of this delivery.
Constraint
A rule or limitation the solution must respect.
Constraints may come from technology, security, time, compatibility, cost, policy, performance, or product decisions.
The tool must remain backward compatible with stored comma-separated domains.
Requirement
A requirement says what must happen. A constraint limits how or under what conditions it may happen.
Assumption
Something treated as true while planning or building.
Assumptions reduce uncertainty temporarily but should be documented and validated when they affect design decisions.
We assume all existing records use valid domain names.
Fact, requirement
An undocumented assumption can quietly become a hidden failure condition.
Acceptance Criteria
Concrete conditions the finished work must satisfy.
Acceptance criteria translate goals into testable statements used to decide whether implementation passes.
Given two valid domains, the adapter returns one comma-separated string in the original order.
Definition of Done, requirement
Acceptance criteria should be verifiable, not vague statements such as “works well.”
Definition of Done — DoD
The full checklist required before work counts as finished.
The definition of done may include implementation, tests, documentation, review, migration, deployment, monitoring, and confirmation that no critical regressions remain.
Code merged, test suite passing, docs updated, and staging verified.
Acceptance criteria
Acceptance criteria describe the feature outcome. Definition of done describes the broader delivery standard.
Deliverable
The concrete thing expected at the end of the work.
A deliverable may be code, a design, a document, a migration, a test suite, a deployed service, or a decision record.
A working adapter plus tests and updated schema documentation.
Milestone
A milestone is a checkpoint. A deliverable is an output.
Milestone
A meaningful checkpoint in a larger project.
Milestones mark progress toward a broader goal and may contain multiple tasks or deliverables.
Complete the first three glossary categories.
Deliverable
A milestone may represent progress rather than a final shippable object.
Exploration — Discovery
The phase where the problem and existing system are investigated before building.
Exploration may include reading code, tracing behavior, inspecting schemas, identifying dependencies, comparing approaches, and documenting risks.
Inspect every Ember capture action before changing the input type.
Implementation, planning
Exploration is not implementation. Its purpose is to reduce uncertainty before code changes begin.
Plan
The proposed sequence of work.
A plan connects the spec to implementation by naming steps, affected areas, risks, dependencies, validation methods, and stopping conditions.
Update the app-side type, add an adapter, migrate callers, and run contract tests.
Specification
A plan should be allowed to change when exploration uncovers new evidence.
Implementation
The actual code or system changes built from a plan or spec.
Implementation is the concrete realization of intended behavior through code, configuration, infrastructure, data changes, or integrations.
Writing the function that converts domain arrays into the tool payload.
Design, deployment
An implementation can run correctly and still fail if it solves the wrong problem or violates the spec.
Iteration
One pass through a cycle of building, checking, and improving.
Iteration is a controlled revision based on evidence from testing, review, feedback, or changed understanding.
The second iteration fixes an edge case found by the adversarial reviewer.
Loop
An iteration is one pass. A loop is the repeating structure that contains multiple passes.
Loop
A process that repeats until a stopping condition is reached.
In workflows, a loop may repeat build, test, review, diagnose, and revise steps.
Build → verify → review → revise → verify again.
Iteration
A loop without a stopping condition can waste time or repeat the same failure indefinitely.
Bounded Loop
A repeating process with a fixed limit.
A bounded loop stops after a defined number of attempts, elapsed time, cost limit, or failure threshold.
Try three repair iterations, then hand the task to a fresh agent.
Infinite loop
A bounded loop needs both an attempt limit and a defined escalation path.
Stopping Condition
The rule that tells a loop when to stop.
A stopping condition may be success, maximum attempts, timeout, budget exhaustion, or a blocker requiring a decision.
Stop when all acceptance criteria pass or after three failed attempts.
Acceptance criteria
Success is one stopping condition. Failure limits and escalation thresholds are others.
Reviewer
A person or agent who examines work for correctness and quality.
A reviewer may assess logic, clarity, maintainability, architecture, test quality, scope, and alignment with the spec.
A reviewer checks the final diff before merge.
Adversarial Reviewer, verifier
A reviewer is not necessarily trying to break the work. Their role is broader quality judgment.
Adversarial Reviewer
A reviewer whose job is to actively try to break the work.
Adversarial review targets hidden assumptions, invalid inputs, edge cases, security flaws, regressions, and misleading success states.
The adversarial reviewer tests duplicate domains, missing fields, and malformed payloads.
Reviewer
Adversarial review is not hostility toward the builder. It is deliberate pressure against the implementation.
Independent Review
A review performed without being anchored to the builder’s preferred solution.
Independent review evaluates the work from fresh context and may catch assumptions shared by the original builder and reviewer.
A separate agent reviews the implementation against the original spec.
Adversarial review
Independent and adversarial are different axes. A reviewer can be independent without actively attacking the system.
Subagent
An agent assigned a narrower task inside a larger workflow.
A subagent receives limited scope, context, tools, and expected output, then reports back to a parent agent or orchestrator.
One subagent explores the codebase while another designs tests.
Agent, worker
A subagent should not automatically inherit unlimited scope or authority.
Orchestrator
The component that coordinates multiple steps, tools, or agents.
An orchestrator assigns work, manages state, orders operations, handles retries, and combines results.
The orchestrator sends implementation to a builder, then verification to a reviewer.
Executor
The orchestrator coordinates the work. It does not need to perform every task itself.
Delegation
Assigning part of a task to another person, agent, or service.
Good delegation defines scope, authority, inputs, expected outputs, constraints, and how results return to the parent workflow.
Delegate schema review to a verifier subagent.
Handoff
Delegation keeps the parent responsible for integration. A handoff may transfer responsibility more fully.
Handoff
Transferring context, evidence, and responsibility to another person or agent.
A useful handoff includes the original goal, current state, decisions, failures, open questions, and next expected action.
Send the fresh agent the spec, diff, test results, and failure log.
Delegation
A handoff without decision history often causes the next agent to repeat failed work.
Escalation
Passing a blocked or high-risk task to a stronger, fresher, or authorized decision-maker.
Escalation occurs when the current workflow reaches a limit, lacks authority, or needs a product, architecture, or safety decision.
After three failed attempts, escalate to a fresh agent with full evidence.
Retry, handoff
Escalation is not failure. It is a designed response to bounded uncertainty or authority limits.
Fresh Agent
A new agent brought in without the original agent’s accumulated assumptions.
Fresh-context review helps reduce anchoring, confirmation bias, and repeated attachment to a failing solution path.
A fresh agent receives the spec and evidence but not the previous agent’s preferred implementation.
Restart
Fresh does not mean context-free. The agent still needs evidence, constraints, and failure history.
Spike
A short exploratory task used to reduce uncertainty.
A spike investigates feasibility, risk, performance, or integration questions without committing to production implementation.
Build a small spike to test whether the provider supports streaming tool calls.
Prototype, proof of concept
A spike is research work. Its code may be disposable.
Proof of Concept — POC
A small build that proves an idea can work.
A proof of concept demonstrates technical feasibility without necessarily being polished, scalable, secure, or production-ready.
A minimal agent that successfully calls one Ember tool through MCP.
Prototype, MVP
A successful POC proves feasibility, not readiness for users.
Prototype
An early version built to explore behavior, design, or interaction.
A prototype may simulate or partially implement a product so teams can learn before committing to full production work.
A clickable glossary prototype with collapsible categories.
Proof of concept, MVP
A prototype explores what the experience should be. A POC usually proves whether something is technically possible.
Minimum Viable Product — MVP
The smallest useful version of a product that can be tested with real users.
An MVP contains enough value to validate demand or behavior while deliberately excluding nonessential work.
A searchable glossary with three categories before the full taxonomy is complete.
Prototype, proof of concept
Viable means genuinely useful, not merely incomplete or low quality.
Architecture
The high-level structure of a system and how its parts fit together.
Architecture defines major components, responsibilities, boundaries, data flow, dependencies, and deployment relationships.
Separating the app-side domain model from the Ember tool payload through an adapter.
Implementation, design
Architecture is not only diagrams. It is the set of structural decisions embodied in the system.
System Design
The process of deciding how a system should be structured and behave.
System design considers components, interfaces, data, reliability, scale, security, trade-offs, and operational behavior.
Designing how memory capture, search, processing, and review interact.
Architecture
Architecture is the resulting structural shape; system design is the process and reasoning that produces it.
Component
A distinct part of a larger system.
A component has a defined responsibility and interface and may be replaced, tested, or deployed separately depending on the architecture.
A search service, UI panel, adapter, or database worker.
Module, service
Component is a broad architectural term. Its exact size depends on context.
Boundary
The point where two parts of a system meet.
Boundaries define responsibility, trust, validation, data conversion, and error handling between components or systems.
The boundary between app-side domain data and the Ember tool payload.
Interface
An interface describes how interaction happens. A boundary is the broader separation where that interaction occurs.
Interface
The defined way one part of a system can interact with another.
An interface describes available operations, accepted inputs, returned outputs, and sometimes behavior guarantees.
A TypeScript interface describing a capture payload.
Contract, schema
Interface can mean a code type or a broader system interaction surface.
Contract
The agreement between two parts of a system.
A contract includes structure and behavioral promises: what is accepted, what is returned, what errors mean, and what must remain stable.
The app promises to send valid domain values; the tool promises to store them.
Interface, schema
A schema covers structure. A contract may also include timing, meaning, side effects, and error behavior.
Schema
A formal description of the expected shape of data.
A schema defines fields, types, allowed values, required or optional status, nesting, and validation constraints.
A tool schema requiring action, domains, salience, and weight.
Contract, type
A schema can be structurally valid while still violating business rules.
Abstraction
A simpler surface that hides unnecessary internal complexity.
An abstraction exposes essential behavior while concealing implementation details behind a controlled interface.
captureMemory() hiding validation, payload conversion, and the underlying API call.
Encapsulation
A bad abstraction hides important behavior or leaks internal details unpredictably.
Encapsulation
Keeping internal state or logic behind a controlled boundary.
Encapsulation limits direct access so callers interact through defined methods or interfaces.
Preventing callers from editing internal memory state directly.
Abstraction
Abstraction simplifies what callers see. Encapsulation controls what callers can access.
Separation of Concerns
Dividing a system so each part handles a distinct responsibility.
Separation of concerns reduces tangled logic by isolating responsibilities such as validation, formatting, storage, and transport.
A validator validates; an adapter reshapes; a client sends.
Single responsibility
Single responsibility focuses on one component. Separation of concerns describes the larger system division.
Single Responsibility
One component should have one clear reason to change.
The principle encourages focused functions, classes, or modules with cohesive responsibilities.
Do not combine validation, database writes, and notification sending in one function.
Separation of concerns
Single responsibility does not mean every function must be tiny. It means its purpose should be coherent.
Coupling
How dependent two parts of a system are on each other.
Tight coupling means changes in one component frequently force changes in another. Loose coupling reduces that dependency.
A UI directly depending on database-specific fields is tightly coupled.
Cohesion
Some coupling is necessary. The goal is controlled, explicit dependency.
Cohesion
How naturally the responsibilities inside one component belong together.
High cohesion means a component’s data and behavior support one focused purpose.
A module containing only capture validation and related types.
Coupling
Good architecture usually seeks high cohesion inside components and lower coupling between them.
Dependency Injection — DI
Giving a component its dependencies from outside.
Dependency injection separates construction from use, allowing real services to be replaced with test doubles or alternate implementations.
Passing a search client into a service instead of creating it inside the function.
Import
Importing a dependency is not the same as injecting a configured instance.
Adapter
Code that makes one interface or data shape work with another.
An adapter translates between incompatible contracts while isolating that translation from the rest of the system.
Converting EmberDomain[] into the comma-separated string expected by the tool.
Mapper, serializer
An adapter exists because two interfaces differ. A mapper may reshape data even within one system.
Mapper — Transformer
Code that converts one data shape into another.
A mapper selects, renames, computes, or restructures fields without necessarily handling transport or compatibility concerns.
Mapping a database record into a public API response.
Adapter, serializer
Mapping changes structure. Serialization changes representation for storage or transfer.
Serializer
Code that converts structured data into a transferable or storable form.
Serialization turns objects or records into formats such as JSON, bytes, or delimited strings.
Turning a domain array into build,relationship for a tool payload.
Mapper, adapter
Serialization changes representation. It does not necessarily change the meaning of the data.
Source of Truth
The authoritative place where a value or rule is defined.
A source of truth is the system or document trusted to resolve disagreement about state, configuration, schema, or business rules.
The canonical domain registry is the source of truth for valid Ember domains.
Cache, copy
Multiple synchronized copies can exist, but only one should be authoritative.
Guard Clause
An early check that exits before invalid work continues.
Guard clauses reject invalid state, missing inputs, permissions, or unsupported conditions near the start of a function.
If content is missing, throw an error before writing to storage.
Validation
Validation may involve many rules. A guard clause is the early control-flow pattern that stops execution.
Invariant
A rule that must always remain true.
An invariant defines a condition the system must preserve across operations and state changes.
Every active thread must have a valid status and unique identifier.
Requirement, validation rule
An invariant applies continuously, not only at the initial input boundary.
Happy Path
The expected successful flow through a feature.
The happy path assumes valid input and functioning dependencies and shows the intended normal outcome.
Valid capture → payload built → tool succeeds → confirmation returned.
Primary use case
Happy-path success does not prove failure handling or edge cases are correct.
Edge Case
A less common but valid situation near the limits of expected behavior.
Edge cases include empty input, one-item lists, maximum values, duplicates, missing optional fields, and timing boundaries.
A capture with no tags or exactly one domain.
Invalid input
Edge cases are often valid inputs. They are not automatically errors.
Failure Mode
A specific way the system can fail.
Failure modes identify triggers, visible symptoms, affected components, recoverability, and expected handling.
The tool times out after writing data but before returning confirmation.
Bug, error
A failure mode describes how failure occurs. A bug is one possible cause.
Side Effect
Anything a function does beyond returning a value.
Side effects include writing data, mutating state, sending messages, making network calls, logging, and changing files.
Saving a memory node to the database.
Return value
Side effects are not automatically bad. They simply require deliberate control and testing.
Pure Function
A function whose output depends only on its inputs and that has no side effects.
A pure function returns the same result for the same input and does not modify external state.
A function that joins an array of domains into one string.
Deterministic function
Purity includes both deterministic output and absence of side effects.
Mutation
Changing existing data in place.
Mutation modifies an object, array, or state container rather than creating a new value.
Calling array.push() changes the original array.
Reassignment
A const object can still be mutated unless its contents are protected.
Immutable
Not changed after creation.
Immutable patterns create new values instead of modifying existing ones, making change history and reasoning more predictable.
Returning a new object with updated tags instead of editing the original.
const
const prevents reassignment of the variable. It does not automatically make nested data immutable.
Idempotent
Running the same operation multiple times produces the same final effect as running it once.
Idempotency protects retries from creating duplicate or compounding side effects.
Setting the same identity document content twice leaves one final document with that content.
Deterministic
An idempotent operation may return different metadata each time while preserving the same final state.
Regression
A new change that breaks behavior that previously worked.
Regressions may affect correctness, performance, compatibility, security, or user experience.
A schema cleanup causes review actions to reject valid requests.
Bug
Every regression is a bug, but not every bug is a regression.
Refactor
Changing the internal structure of code without intentionally changing its behavior.
Refactoring improves clarity, maintainability, reuse, or architecture while preserving externally observable behavior.
Extracting payload conversion into a dedicated adapter.
Feature change, rewrite
A refactor can still cause regressions, so preserved behavior must be tested.
Technical Debt
Shortcuts or accumulated design problems that make future work harder.
Technical debt includes fragile architecture, missing tests, duplicated logic, outdated dependencies, unclear contracts, and deferred cleanup.
Keeping domain values as unvalidated free strings across the codebase.
Bug
Technical debt is not always accidental. Teams may accept it deliberately for speed, but the cost remains.
Breaking Change
A change that forces existing callers, users, or data to adapt.
Breaking changes alter a public contract, behavior, format, or compatibility guarantee.
Changing domains from comma-separated text to an array without an adapter.
Regression
A breaking change can be intentional and correctly implemented. A regression is unintended damage.
Backward Compatible
Existing callers or data continue to work after a change.
Backward compatibility preserves previously supported contracts while adding or changing behavior safely.
Accepting both legacy domain strings and the new array format during migration.
Forward compatible
Backward compatible does not mean every old behavior must remain forever. It means the transition is supported.
Migration
A controlled move from an old structure or system to a new one.
Migrations may transform stored data, schemas, configuration, APIs, infrastructure, or callers while preserving correctness.
Converting stored domain strings into validated arrays.
Deployment
Deployment releases code. Migration changes state or structure and may happen before, during, or after deployment.
Branch
A separate line of development in Git.
A branch points to a sequence of commits and lets work progress without directly changing another branch.
Create a feature branch for the glossary search update.
Fork
A branch usually exists inside the same repository. A fork is a separate copy of the repository.
Commit
A saved checkpoint of code changes in Git.
A commit records a snapshot, author, timestamp, parent history, and message describing a coherent change.
Commit the domain adapter and its tests.
Push
A commit is saved locally first. Push sends commits to a remote repository.
Push
Sending local Git commits to a remote repository.
Push updates a remote branch with commits from the local repository.
Push the feature branch so the reviewer can open the PR.
Commit, array push
Committing does not automatically send changes to GitHub or another remote.
Pull Request — PR
A request to review and merge one branch into another.
A pull request presents the diff, discussion, automated checks, approvals, and merge status for a proposed change.
Open a PR from glossary-search into main.
Pull, merge
A PR does not automatically merge code. It is the review and integration request.
Diff
The exact lines added, removed, or changed between two versions.
A diff is a comparison artifact used for review, debugging, patching, and understanding scope.
Review the final diff before committing.
Commit
A commit is a saved change set. A diff is the comparison showing what changed.
Merge
Combining changes from one branch into another.
A merge integrates histories and may create a merge commit or use another merge strategy.
Merge the approved PR into main.
Rebase
Merge combines histories. Rebase rewrites where commits appear to begin.
Merge Conflict
A situation where Git cannot automatically combine competing changes.
Conflicts occur when changes overlap incompatibly or Git cannot determine the intended final content.
Two branches edited the same schema line differently.
Test failure
A merge conflict is a version-control problem, not proof that either implementation is logically wrong.
Rebase
Moving a branch’s commits so they appear on top of a newer base.
Rebase rewrites commit ancestry to create a cleaner linear history or update work against the latest branch state.
Rebase the feature branch onto main before review.
Merge
Rebase rewrites history and should be used carefully on shared branches.
Squash
Combining several commits into one.
Squashing simplifies history by replacing multiple related commits with a single coherent commit.
Squash the fixup commits before merge.
Rebase
Squash changes commit history, not the final file content by itself.
Cherry-pick
Copying one specific commit onto another branch.
Cherry-pick applies the change represented by a selected commit without merging the entire source branch.
Cherry-pick the hotfix into the release branch.
Merge
Cherry-picking duplicates the change into a new history rather than sharing the original branch relationship.
Revert
Creating a new commit that reverses an earlier commit.
Revert preserves history while applying the opposite change of a selected commit.
Revert the schema change that broke production.
Rollback, reset
Revert does not erase history. It adds new history that undoes the effect.
Rollback
Returning a system to an earlier working state.
Rollback is the operational act of restoring code, configuration, data, or deployment state after a failed release.
Roll back the deployment while the bug is investigated.
Revert
Revert is a Git action. Rollback is the broader recovery operation.
Patch
A focused set of code changes.
A patch may fix a bug, change behavior, or update security without representing a full feature release.
A patch correcting optional field validation.
Hotfix
A patch describes the size or form of the change. A hotfix describes urgency and production context.
Hotfix
An urgent fix for a live problem.
A hotfix follows an accelerated release path to correct a production issue while minimizing additional change.
Ship a hotfix for captures failing in production.
Patch
Urgency does not remove the need for review, tests, and rollback planning.
Continuous Integration — CI
Automatically running checks when code changes.
CI systems build, lint, typecheck, and test proposed changes so problems are caught before integration.
Every PR runs the TypeScript and test suites.
Continuous deployment
CI validates changes. It does not necessarily deploy them.
Pipeline
An automated sequence of build, test, review, or deployment steps.
A pipeline defines ordered jobs, dependencies, conditions, artifacts, and failure handling.
Install → typecheck → unit tests → build → deploy preview.
Workflow
Pipeline often refers to automation machinery. Workflow can also include human or agent steps.
Lint
Checking code for style problems and suspicious patterns.
A linter performs static analysis using configurable rules and may report or automatically fix issues.
The linter flags an unused variable.
Typecheck, format
Linting can catch some bugs, but it does not prove type or runtime correctness.
Typecheck
Checking whether values and operations match their declared types.
Typechecking verifies type contracts without necessarily running the program.
Rejecting a string where an EmberDomain array is required.
Lint, runtime test
Typechecking proves type consistency, not complete behavioral correctness.
Unit Test
A test for one small piece of logic in isolation.
Unit tests exercise a function, class, or module with controlled inputs and dependencies.
Testing that joinDomains returns build,relationship.
Integration test
A unit test can pass while the full workflow still fails.
Integration Test
A test that checks whether multiple parts work together.
Integration tests verify boundaries, adapters, services, databases, or APIs in combination.
Testing that a CaptureDraft becomes a valid Ember tool request.
Unit test, E2E test
Integration tests cover connected components but may not exercise the full user journey.
End-to-End Test — E2E
A test of the complete workflow from beginning to end.
E2E tests exercise the system through realistic interfaces and dependencies, often as a user would.
Submit a capture form, validate it, call the tool, store the node, and display success.
Integration test
E2E tests are powerful but slower and often more fragile than smaller tests.
Eval — Evaluation
A structured measurement of how well an AI system performs.
Evals may score correctness, relevance, judgment, tone, safety, consistency, tool use, or schema adherence.
Checking whether an agent chooses the correct Ember domains across 100 examples.
Test, benchmark
A software test often has exact expected output. An eval may measure quality using rubrics, judges, or statistical thresholds.
Table Test — Table-Driven Test
One test pattern run against many rows of inputs and expected outputs.
Table tests keep repeated test logic in one place while varying cases through structured data.
Testing one domain, two domains, no tags, and invalid values through the same formatter test.
Data table
The table is usually an array or list of cases, not necessarily a visual spreadsheet.
Fixture
Prepared data used repeatedly in tests.
Fixtures create known starting state for users, records, files, responses, or environments.
A valid capture fixture with domains, salience, and weight.
Mock
A fixture is test data or setup. A mock replaces behavior.
Mock
A fake dependency with controlled behavior and expectations.
Mocks replace real components and may verify how they were called.
Mock the Ember client and assert it received the correct payload.
Stub, spy
Mock, stub, and spy are related test doubles but emphasize different behavior.
Stub
A simple fake that returns predefined results.
A stub replaces a dependency so the test receives predictable output without using the real system.
Stub search to return two known nodes.
Mock
A stub mainly supplies behavior. A mock commonly verifies interaction.
Spy
A test helper that records how a function was called.
A spy tracks call count, arguments, order, and return behavior while sometimes preserving the original implementation.
Spy on sendMessage to confirm it ran once with the expected channel ID.
Mock
A spy observes calls. It does not always replace the implementation.
Smoke Test
A quick check that the major system paths are alive.
Smoke tests verify basic availability and critical functions after a build or deployment.
Confirm the app loads, authentication works, and one tool call succeeds.
Sanity test
Smoke tests are broad and shallow. They do not prove every feature works.
Sanity Test
A narrow check that a specific change behaves plausibly.
Sanity testing focuses on the area just changed rather than exercising the entire system.
Confirm the adapter still joins domains correctly after refactoring.
Smoke test
Smoke asks “Is the system broadly alive?” Sanity asks “Does this particular change appear sound?”
Contract Test
A test that checks whether two systems still agree on their interface.
Contract tests validate requests, responses, schemas, errors, and compatibility between producers and consumers.
Verify the app payload still matches the Ember tool schema.
Integration test
A contract test may run without the full real system if both sides share or verify the same contract.
Flaky Test
A test that passes and fails inconsistently without a meaningful code change.
Flakiness often comes from timing, shared state, network dependency, randomness, or poor isolation.
An E2E test fails one run in ten because the page loads slowly.
Nondeterministic system behavior
Repeatedly rerunning a flaky test until it passes hides the problem and weakens trust.
Coverage — Code Coverage
A measurement of how much code is executed by tests.
Coverage may report statements, branches, functions, or lines exercised during test runs.
The unit suite covers 90% of branches.
Test quality
High coverage does not prove the tests check meaningful behavior.
Deploy
Putting a version of the software into a running environment.
Deployment may publish code, start services, update infrastructure, migrate data, and configure runtime settings.
Deploy the approved build to staging.
Release, implementation
Deployment is the act of placing code into an environment. Release is making it available for intended use.
Release
A version of software made available for use.
A release groups approved changes, versioning, notes, artifacts, compatibility decisions, and rollout strategy.
Release version 2.4.0 after staging verification.
Deployment
A build can be deployed internally without being released to users.
Staging
A production-like environment used for final testing before release.
Staging mirrors important production configuration and integrations while remaining isolated from live users or data where possible.
Run the full capture workflow in staging before production.
Development, production
Staging is useful only if it resembles production closely enough to reveal real integration issues.
Production — Prod
The live environment used by real users.
Production carries real traffic, real data, operational risk, monitoring, and reliability expectations.
The hotfix is now live in production.
Staging
A change working locally or in staging does not guarantee it will behave identically in production.
Canary Release
Releasing a new version to a small portion of traffic first.
Canary rollout limits risk by measuring real behavior before expanding to all users.
Send 5% of requests to the new router.
Feature flag
A canary controls exposure by traffic or instances. A feature flag controls whether a feature is enabled.
Shadow Mode
Running a new system alongside the current one without letting it affect users.
Shadow mode receives copies of real inputs and records outputs for comparison while the existing system remains authoritative.
Run the new agent router in shadow mode and compare decisions.
Canary release
Canary output affects a small group of users. Shadow output affects none.
Artifact
A produced file or output from a build or workflow.
Artifacts include binaries, packages, reports, generated sites, test results, screenshots, or deployment bundles.
The built glossary HTML file is a release artifact.
Deliverable
A deliverable is the expected outcome. An artifact is a concrete produced object, often generated by the process.
Incident
A production problem requiring coordinated response.
Incidents affect availability, correctness, security, data, or user trust and are managed through detection, mitigation, recovery, and follow-up.
Captures are failing for all users after deployment.
Bug
A bug becomes an incident when its live impact requires operational response.
Postmortem
A structured review after an incident.
A postmortem documents impact, timeline, root cause, contributing factors, response, and prevention work.
Write a blameless postmortem after the capture outage.
Failure log
A good postmortem is not a blame document. It explains system conditions and improves future resilience.