The Harborline story: from a missed promise to an operating application

This is a fictional worked example, not a report of completed software development. Approval decisions, prototypes, test observations, deployments, and outcomes described below occur within the story. See the company inventory, framework checklist, and decision/evidence packet for the supporting artifacts.

Step 01: Intake

On a Monday morning, a packaging plant calls Priya, a Harborline branch coordinator. A technician has arrived for a compressor repair, but the replacement seal was allocated to another job. The customer's production manager had arranged a line shutdown around the appointment. The technician has the right qualification; the customer has provided access; the part is the missing prerequisite. Three people had checked availability on Friday, but none had confirmed a reservation.

Maya, the COO, initially asks for a customer portal that shows every job's status. Luis, the service director, asks the team to separate the proposed product from the business problem. A portal might make the wrong promise more visible without making it more reliable. He opens initiative HIS-027: “Reduce service commitments that fail because known prerequisites were not secured.”

Analysis. The failure has a direct cost—travel and rescheduling—and a customer trust cost. Neither is yet quantified. The team does not assume that a single complaint represents all branches. It records the incident, affected customer journey, and competing explanations: inaccurate inventory, unclear reservation policy, premature dispatch, or a user bypass. The inquiry has an owner and a limited discovery budget rather than a predetermined software solution.

Action and artifact. Genesis holds the problem statement and sponsor decision; the incident's actual operations record remains in ServiceNow. Priya introduces a temporary pre-dispatch checklist for complex requests. This is immediate containment, not proof that the underlying problem is solved.

Gate. Maya approves investigation, not a portal build. The customer portal becomes a candidate idea in the backlog. If discovery shows one isolated training error, the initiative may close with a process correction. Framework step 01 is complete in the narrative.

Step 02: Discover

Luis and Priya walk through requests with sales, procurement, dispatchers, technicians, and customer service. Instead of asking users which screens they want, they follow ten recent successful requests and ten failures from intake to invoice. They then use the six-week reporting sample to quantify the pattern.

The current process is: accept the request; check contract coverage; check apparent parts availability; ask dispatch about a technician; agree a date; reserve parts; book the slot; notify the customer. The dangerous ordering is visible: the agreed date often precedes the actual reservation. A successful case usually involves a coordinator who informally knows whom to call. The process depends on personal knowledge that is absent during holidays or shift changes.

Analysis. The baseline contains 960 eligible complex requests and 115 failed commitments. Simple requests are excluded because they do not have the same coordination burden. Weather closures and customer cancellations are separately coded. The team also examines failures caused by inaccurate promises versus unforeseeable events. If the new tool reclassifies failures as cancellations, a dashboard could improve while customer outcomes do not.

Time studies show average coordination effort of 26 minutes for eligible requests, spread across several short interruptions. The study distinguishes active work from elapsed waiting time; reducing clicks does not necessarily reduce the calendar time required to obtain a part.

Action and artifact. The process map, outcome definitions, baseline query, and interview summaries become DISC-027 r1. Scope receives findings with source links. No customer-sensitive transcripts are copied into unrestricted delivery tickets.

Gate and framework change. Luis confirms a recurring coordination problem. Revision 1.1 adds stable denominators, exclusion reasons, and successful counterexamples to the discovery checklist. A future benefits review must use these definitions or explicitly explain a revision.

Step 03: Inventory

Jordan, the architect, brings the application owners into a workshop. The first surprise is that Harborline already has several places capable of displaying a job. Salesforce knows the customer. ERP knows the stock and reservations. Field Service knows the work order, technician skills, and dispatch slot. SharePoint contains a spreadsheet that tries to combine all three.

The inventory records more than product names. It identifies the authoritative records, local interface owners, access constraints, data freshness, operating responsibilities, and contractual assumptions. Nia explains that warehouse inventory snapshots are suitable for reporting but unsafe for promising the last available part. Ethan explains that a suggested field-service slot is not a confirmed dispatch assignment.

Analysis. The team separates four possible gaps: missing functionality, unavailable licensing, poor configuration, and weak process ownership. A product may support an extension while the local team lacks authority or capacity to maintain it. Conversely, a missing feature in today's screen does not establish that new custom software is justified.

The strongest incumbent candidate is Field Service because dispatch users already work there. CRM is also considered, but broad operational adoption would expand its user population and still require reservation logic elsewhere. ERP is authoritative for parts but is a poor location for every customer coordination interaction under the company's assumed operating model.

Action and artifact. Jordan produces the P01–P18 inventory. Owners mark interface permissions and licensing as assumptions to be validated in the spike. The enterprise warehouse stays out of the live confirmation path.

Gate. Architecture review accepts the inventory as sufficient for comparison, with explicit open dependencies. It does not approve the assumed interfaces as production-ready. If Nia cannot provide a supported reservation interface, the solution decision must change.

Step 04: Define outcomes

Daniel, the finance partner, asks what “better coordination” would mean in a funding review. Luis proposes cutting the eligible-request failure rate from approximately 12% to at most 6%, while reducing average active coordination time from 26 to 16 minutes. Maya adds a boundary: emergency requests must remain possible through accountable exceptions.

The financial model is less attractive than the original enthusiasm suggested. At the target, 480 avoided failures per year at $300 each yield $144,000 of avoided direct cost. Released coordinator time has value, but Daniel refuses to count all of it as cash savings when there is no staffing reduction or specific redeployment plan. The estimated recurring custom-system cost is $90,000 annually.

Analysis. At the initial funding ceiling of $302,400, simple payback from direct avoided cost net of recurring cost is approximately 5.6 years. A smaller improvement could fail to cover ongoing cost. The pilot therefore needs a strategic reliability rationale and a credible stop decision. The team records customer retention as a hypothesis, not an invented financial benefit.

Goals can also conflict. A coordinator could reduce failures by refusing all difficult requests. To detect this, the pilot tracks deferrals, declined requests, override frequency, request volume, and customer wait time alongside failed commitments. Faster work that increases unauthorized commitments is not success.

Action and artifact. CASE-027 r1 states the financial assumptions, outcome targets, guardrail metrics, and non-goals. The sponsor reserves a capped investigation allocation within the eventual total estimate; the full delivery budget is not released yet.

Gate. Maya approves further evaluation because the customer reliability issue is strategically important. Daniel records the weak short-term financial payback explicitly. Enterprise deployment remains contingent on evidence, rather than guaranteed by the initial sponsorship.

Step 05: Develop requirements

Priya demonstrates the smallest useful workflow. A coordinator opens a work order, sees each prerequisite and its freshness, requests confirmation, and receives either a supported commitment or a specific blocking reason. A supervisor can handle a bounded emergency exception. A support operator can resolve an uncertain transaction without guessing whether the ERP committed it.

Scope turns these examples into requirements, while Blueprint holds the versioned specification. Jira receives delivery items linked to those requirement IDs; the team avoids maintaining independent status in all three tools. Where a native connector is unverified, the pilot uses reviewed exports with stable IDs.

Analysis. “Single pane of glass” is replaced with observable behaviors. “Real time” becomes a visible freshness policy. “Reliable” becomes explicit recovery, idempotency, and reconciliation behavior. “Secure” becomes branch authorization, role separation, deprovisioning, and audit events. The team gives each requirement an owner and acceptance example before estimating implementation.

Luis distinguishes a policy exception from a data-integrity exception. A supervisor may authorize a business exception within a defined rule, but cannot assert that an unknown reservation succeeded. This prevents the override feature from becoming a way to bypass basic transaction correctness. A customer-facing promise remains dependent on known authoritative state.

Action and artifact. The initial specification contains R01–R11, with later revisions tracked in the evidence packet. For R02, the acceptance example deliberately uses two coordinators attempting to reserve the same final part. For R09, the example requests another branch's record directly through the API, not merely through a hidden UI link.

Gate. Luis approves the minimum business scope. Security and SRE accept testable targets for their domains. Customer self-service, new invoicing, and route optimization stay outside the first release. Unresolved policy is returned to its owner rather than delegated implicitly to a developer.

Step 06: Choose a solution

Jordan presents six options: process-only controls, a CRM extension, a Field Service extension, a low-code composition, a specialist purchase, and a narrow custom workspace. Each is evaluated against the same requirements and cost boundary. The team first applies hard constraints for authorization, authoritative reservations, recovery, ownership, and a bounded pilot.

The weighted matrix produces a near tie: custom scores 3.80, Field Service extension 3.75. Maya asks why the team should accept custom complexity for such a small difference. Jordan explains that the number is a prompt for scrutiny, not a mathematical approval. The distinction rests on whether Harborline can safely own a cross-system recovery worker and whether the incumbent extension would need essentially the same worker.

Analysis. The fictional local Field Service customization boundary makes the recovery behavior awkward, but that is a tenant-specific finding to validate, not a statement that the commercial product is incapable. The low-code option is strong for straightforward approvals; its prototype has not established durable reconciliation after a remote timeout. The purchase option remains possible, but the vendor demonstration has not proven the critical ERP behavior.

Sensitivity analysis matters: a one-point improvement in the Field Service cost score makes it the leader. A one-point loss in custom recovery also reverses the choice. Jordan therefore refuses to authorize full delivery from workshop scores alone.

Action and artifact. ADR-001 r1 conditionally selects a small custom coordination application. It explicitly excludes rebuilding scheduling or inventory. The record includes the incumbent extension as the fallback, the estimate range, and the assumptions that can reverse the decision.

Gate. The sponsor authorizes a time-boxed spike. No team receives an unlimited mandate to build a platform. A failed interface or unsupported operating model sends the initiative back to this stage.

Step 07: Validate assumptions

The spike lasts two weeks within the delivery estimate. One engineer and the ERP owner exercise the reservation interface, while the architect and application owner verify the local extension and entitlement constraints. They use synthetic accounts and parts in a controlled environment.

The happy path works quickly. The decisive test is less comfortable: the ERP creates a reservation, but the response is lost before the workspace receives it. A naive retry creates a duplicate request. The team pauses to distinguish a timeout from a failed transaction. The workspace cannot infer the remote outcome from its own missing response.

Analysis. Under the story's verified interface assumption, ERP supports a stable external request key and lookup by that key. A retry worker can query the original outcome and associate the reservation once. Concurrency tests also establish that the ERP rejects an incompatible competing reservation. These are the exact capabilities a real implementation must prove; a generated client library is not evidence of safe semantics.

The comparison spike confirms that the local Field Service extension would still use an external worker for this sequence. Its initial speed advantage is smaller for the hardest part of the problem. This supports the custom decision without claiming that a custom solution is universally superior.

Action and artifact. SPIKE-027 r1 records response-loss, duplicate submission, version conflict, permission denial, and rate-limit scenarios. ADR-001 r2 confirms the narrow custom boundary. R03 gains explicit UNKNOWN state and reconciliation acceptance criteria.

Gate and framework change. The architecture gate proceeds because the critical assumptions have narrative evidence. Framework revision 1.2 requires partial-success recovery proof before design approval. If the ERP owner had rejected the lookup mechanism, the decision would have returned to step 06 regardless of sunk effort.

Step 08: Design

Schema gives the team a shared model for commitments, versions, observations, reservation attempts, exceptions, audit events, and outbox messages. The first design review catches a table called InventoryBalance. Nia objects: storing an apparently authoritative balance invites users and developers to treat it as stock truth. The team changes it to a timestamped prerequisite observation with the ERP source identified.

Blueprint links the model to R01–R11 and the architecture decision. Developers review generated SQL as design input, then write versioned migrations. The schema diagram does not automatically become a safe database upgrade plan.

Analysis. The system uses local transactions plus explicit remote steps. A database transaction can commit the workspace state and notification outbox together; it cannot atomically commit an ERP reservation and a dispatcher assignment. If the part is reserved but the slot cannot be confirmed, the workspace records the partial outcome and requests an acknowledged release or a human decision. It does not silently erase the reservation reference.

Security review identifies cross-branch access, forged override requests, overprivileged service credentials, and sensitive log content as concrete threats. The design uses server-side authorization and scoped identities. The team records the retention policy owner and keeps HR compensation out of the operational data model.

Action and artifact. DESIGN-027 r1 includes entity ownership, the state machine, adapter contracts, authorization rules, and recovery sequences. An isolated restore plan explicitly includes comparing restored local records with upstream operations that may be newer than the backup.

Gate. The system owners approve the boundaries; Sofia approves the planned security controls subject to verification. Grace accepts ownership of the recovery design. The gate would reopen if the solution required direct writes into ERP tables or expanded to customer self-service.

Step 09: Fund and plan

Owen turns the design into vertical slices: read-only coordination view; controlled reservation and confirmation; reconciliation and exception handling; and pilot reporting and operations. The team can demonstrate a complete business path at each increment instead of separately finishing every screen and then discovering that the adapters do not work together.

The ten-week delivery window uses 2,400 cross-functional hours, including the two-week spike. Three engineers contribute 900 hours, one QA engineer 300, product and service subject-matter experts 400, platform/security/architecture specialists 500, and training and operational acceptance 300. These are available project hours after other commitments, not nominal full-time totals. Specialist participation must be scheduled when design and verification need it.

Analysis. Chronos supplies historical actuals for comparable integration work. HR calendars and managers establish future availability. Fiscal supplies relevant expense context; Ledger tracks the funding envelope and commitments; finance reconciles both against ERP. An invoice arriving late does not make the project cheaper, and unused budget does not create extra engineering capacity.

The $252,000 baseline comprises $240,000 labor plus $12,000 environments/integration allowances. Contingency raises the funding ceiling to $302,400. Owen holds scope within the available skills rather than treating every hour as interchangeable. If the ERP owner is unavailable during the reservation slice, adding a frontend developer does not remove the bottleneck.

Action and artifact. PLAN-027 r1 links each slice to requirements, dependencies, owners, and acceptance. Jira remains authoritative for task execution. The team records what to remove first if effort rises: richer reporting and optional convenience features, not recovery or authorization.

Gate. Maya and Daniel authorize the bounded delivery budget after the spike. Grace accepts an operating allocation. Any increase beyond the ceiling or expansion of the business boundary returns for investment review.

Step 10: Standardize

The platform lead proposes Foundry. Owen is concerned that introducing a generation platform during a delivery project may create more work than it saves. They agree to a limited trial: generate an API service and an integration worker from one approved baseline, then measure the effort to build, understand, and update both.

The template defines project structure, configuration loading, structured logs, health endpoints, test entry points, and CI starters. It contains no real secrets or business decisions. The platform team pins the template version and stores generation metadata with the repositories. Generated changes enter ordinary pull requests.

Analysis. Consistency is useful when developers move between services and when security changes must reach multiple codebases. However, generation at creation time does not enforce future conformance. The platform lead must maintain the template, define exceptions, and show how an existing service receives a baseline update without overwriting handwritten logic.

In the narrative trial, both services build from the baseline and a logging update reaches both through reviewed update PRs. The team records the manual work required and treats it as ongoing ownership cost. It does not claim that Foundry automatically upgrades all generated code. If the update trial had failed, a reviewed starter repository would have been acceptable.

Action and artifact. BASELINE-027 r1 records the template version, platform owner, required checks, permitted deviations, and upgrade procedure. This pilot is included in the delivery hours rather than hidden as free platform work.

Gate. Foundry is accepted for these two service components. Enterprise-wide template adoption remains a separate decision. The framework continues to allow a simpler baseline when generation does not justify its complexity.

Step 11: Implement

The first demonstration is deliberately modest. Priya opens a work order and sees account, part, and dispatch references with source timestamps. When the ERP is unavailable, the screen says “Part readiness unknown” and shows the last successful observation. The team resists replacing that message with a reassuring green icon based on yesterday's data.

The second slice adds the reservation request and durable state transitions. Engineers implement server-side branch authorization, optimistic locking, stable external request keys, and the outbox. They place a feature control around confirmation so read-only use can continue if the transaction path needs to be disabled.

Analysis. Implementation reveals how quickly a UI can misrepresent asynchronous work. “Request submitted” must differ from “Commitment confirmed.” A successful HTTP response from the workspace can mean that work was accepted for processing, not that the ERP and dispatch systems have confirmed it. API response shapes, button labels, and support instructions all use the same distinction.

Code review checks the negative cases as well as style. A cancellation must preserve audit history. A repeated notification must not create a new commitment. A schema change must remain compatible with the previous application version during rollout. Developer convenience endpoints cannot bypass authorization in the pilot environment.

Action and artifact. Each PR links its Jira work item and requirement IDs. Test runners execute unit and adapter contract checks. The build produces an immutable artifact reference; a real project would record its full commit and digest rather than the narrative's BUILD-027-04 label.

Gate. The complete narrow path is admitted to formal verification. Optional analytics remain outside the candidate. Successful local demonstrations do not count as business UAT or recovery acceptance.

Step 12: Verify

Amina starts with the failure that justified the architecture: the ERP commits a reservation and the response disappears. She restarts the worker before the local association is saved, then replays the same action. The expected result is one ERP reservation, one recovered association, and a visible audit trail—not merely an HTTP 200.

Additional tests use two coordinators racing for the same part, stale observations, unauthorized cross-branch requests, duplicate notifications, revoked access, and a dispatch rejection after reservation. Performance runs use 50 concurrent sessions and representative data. Grace conducts an isolated backup restore and the upstream reconciliation exercise.

Analysis. A test suite can pass while the evidence is unusable if it belongs to a different build. ArcoreTest catalogs results only after import behavior and identity mapping are checked. Blueprint links the requirement revision and candidate record. Unknown or skipped security results cannot become a green release summary through an import default.

The fictional first verification candidate fails a cancellation test: it hides the unresolved ERP release request. Engineering fixes the transition and adds a regression case. The changed artifact receives a new candidate identity and affected checks are rerun. The team does not preserve the earlier approval merely because the code change is small.

Action and artifact. The final narrative candidate meets the stated performance thresholds and the two-hour RTO / fifteen-minute RPO exercise targets. Its evidence includes remote-state reconciliation, not just database restoration. Findings and residual limitations are attached to the candidate record.

Gate. Amina and Sofia approve advancement to UAT after the required checks pass. This is a verification gate, not authorization to deploy to all branches. A new artifact or material configuration change would invalidate affected evidence.

Step 13: Accept

Priya and a second branch coordinator use realistic work orders in staging. They perform a normal commitment, a stale-data case, an emergency exception, and a recovery handoff. Luis watches the task completion rather than giving the users instructions at every difficult step.

The software correctly restricts override approval to supervisors. But the evening exercise reveals a business gap: the assigned supervisor is not available after 6 p.m. The team had tested permissions without testing staffing coverage. An emergency feature that depends on an absent approver is not operationally usable.

Analysis. The tempting workaround is to give all coordinators supervisor access. Sofia rejects this because it removes the separation the business requested. Luis instead establishes an on-call delegation policy with a time-limited alternate supervisor. The coordinator requesting an exception cannot approve the same exception. The app displays the eligible approver and the escalation route.

The team also finds a validation error that clears entered reason text. This is a small implementation defect but a substantial usability problem during a stressful call. Keyboard-only task completion and non-color status cues are included in the acceptance pass rather than treated as cosmetic polish.

Action and artifact. The policy and requirement revision are recorded, related code and tests change, and affected verification is repeated. Controlled evidence files contain scenario, operator, candidate identity, observation, and acceptance decision. UATCLI is used only if the separate UAT service is validated; the story's minimum path works with reviewed files.

Gate and framework change. Luis accepts the revised flow for the pilot branch. Framework revision 1.3 adds delegated authority and shift coverage to acceptance. Users are trained on UNKNOWN and escalation; they are not told that retrying repeatedly will fix uncertainty.

Step 14: Release

Grace schedules the release with one branch, four coordinators, the ERP owner, and dispatch support available. The team deploys the same artifact approved in staging through the existing GitHub Actions path. Adding Parkour at this point would introduce another deployment dependency without solving a demonstrated need.

The workspace initially runs read-only. Users compare its source references with existing systems, and the team resolves discrepancies. Confirmation is then enabled for the selected branch. The old spreadsheet is made read-only for the pilot workflow after reconciliation; other branches retain their established process until separately migrated.

Analysis. Rollback has two meanings. The application binary can return to an earlier compatible version, but ERP reservations created during the pilot remain real. A rollback procedure must stop new confirmations, identify in-flight and UNKNOWN requests, and reconcile external state before users resume manual actions. Restoring a database backup is not a safe shortcut for cancelling business transactions.

Grace defines hold conditions: unavailable on-call coverage, unresolved source-state discrepancies, missing candidate evidence, or a failing authorization check. The feature control can disable confirmations while keeping read-only support views available. A controlled manual procedure records requests with correlation references so operators do not accidentally repeat an uncertain reservation.

Action and artifact. The change record includes the candidate identity, configuration revision, branch scope, approvers, support contacts, monitoring links, and rollback sequence. Notifications inform affected staff; they are not treated as approvals.

Gate. The release owner authorizes the branch pilot only. The initial smoke checks verify sign-in, branch restrictions, a controlled commitment, audit events, and source freshness. Broader rollout remains unchecked in the framework.

Step 15: Operate and learn

During the second week, three reservation attempts remain UNKNOWN longer than expected. The API is responding, the database is healthy, and the dashboard's endpoint checks are green. Priya escalates when the coordinator queue stops progressing.

Grace opens a ServiceNow incident and disables new confirmations for affected work. Proof organizes hypotheses and evidence. The investigation finds that a retry worker mishandles a rate-limit response and stops advancing a subset of requests. The reservations are not duplicated because the stable-key protection works, but safe uncertainty still causes delay. One request misses its agreed window and counts as a failed commitment.

Analysis. Availability of the web server is not equivalent to health of the business workflow. Nexus's normalized component view is useful, but it cannot infer that a queue is stuck unless the relevant metrics exist. The enterprise monitoring stack needs oldest unresolved request age, reconciliation lag, source freshness, and worker heartbeat signals. A green HTTP response cannot replace those measures.

The team fixes retry scheduling, reconciles the three requests against ERP, and adds a stalled-worker regression case. R12 is created with measurable alert thresholds. The new requirement and changed candidate receive fresh verification and release acceptance. The incident is not closed solely because the worker process restarts.

Action and artifact. INC-027-01 links the cause, affected requests, recovery evidence, corrective work, and BUILD-027-05. The service owner validates the alert with an intentionally stalled worker in a controlled test.

Gate and framework change. The affected path resumes after reconciliation and approval. Revision 1.4 adds queue age and data-freshness evidence to operational readiness. The framework is improved by a real failure inside the story, not by adding an unrelated checklist item after the fact.

Step 16: Evaluate outcomes

After four pilot weeks, Maya asks whether Harborline should deploy to all eight branches. Luis presents the outcome ledger, including the incident. The pilot branch records seven failed commitments in 120 eligible requests, compared with fifteen in its preceding comparable period. Average coordination time falls from 26 to 17 minutes.

The results are promising but mixed. The failure-rate point estimate meets the 6% target; the ten-minute time-reduction goal is not yet achieved. A similar comparison branch improves slightly without the application. Daniel explains that the samples are small and that case mix, staff attention, and the temporary process improvements may contribute. The team does not claim that the difference is a proven causal effect.

Analysis. The build spends $257,000: $246,000 labor and $11,000 environments/integration. That exceeds the baseline by $5,000 but remains within the approved ceiling. The additional labor is recorded, not hidden by comparing only against contingency. Recurring ownership assumptions still need longer observation. Released coordinator time must be assigned to useful work before it becomes realized capacity value.

The operating review also evaluates override frequency, deferred requests, stale data, customer wait time, support burden, and branch adoption. If fewer failures had come from rejecting difficult work, the project would need correction even with a favorable headline metric. The comparison branch and baseline definitions are retained for the next cohort.

Action and artifact. BENEFIT-027 r1 recommends planning a second bounded cohort, extending observation, and reviewing license/interface costs before expansion. Maya approves that planning step. She does not approve immediate enterprise rollout or declare the financial benefits proven.

Gate. The initial story closes with a working application in a limited fictional pilot, an operating owner, a documented incident-learning loop, and an explicit next decision. The framework leaves enterprise rollout, final spreadsheet retirement, and long-term continuation reviews unchecked. The team has converted a business problem into testable requirements and an operating solution while retaining the option to change course.

What the next story increment must resolve

The second cohort should test a branch with different staffing and parts patterns, verify whether the exception policy scales, measure recurring support effort, and compare achieved benefits with the forecast. It should also decide whether Foundry's baseline maintenance and the selected Arcore evidence tools reduce total delivery effort enough to justify their operating cost.

Expansion would require the same evidence discipline as the first branch: validated local interfaces, authorized users, trained operators, support coverage, source-state reconciliation, and an approved candidate. The framework should change only when new evidence exposes a missing decision or control, with the revision recorded in its change log.