# Opportunity Radar — System Definition

From utility signals to an informed next step.

_Question status: **0 open · 3 routed to future work · 6 resolved**._

## One paragraph

Radar brings public utility project signals together into useful briefs in Salesforce, so your team can understand what is changing, investigate what matters and decide when to pursue an opportunity.

## The company journey

Utility infrastructure delivery and business development

### Public sources

Tender notices and utility project pages reveal signals worth checking.

Utility capital plans, tender notices, addenda, project holds and prequalification or site-visit requirements can describe transmission, substation, civil access and engineering work.

- **Inputs:** Capital plans, tenders and addenda
- **Signals:** Scope, gates, holds and site visits
- **Cadence:** Checked on request

### Signals

Source-linked observations gather around the same initiative.

Signals can identify a planned line or substation bay, a pre-bid site visit, a revised civil-access scope or a later project hold.

- **Examples:** Line, bay, site visit and access-road signals
- **Support:** Passages, dates and source identity
- **Uncertainty:** Conflicts remain visible

### Maintained briefs

Related signals give rise to a useful, changing brief.

A brief brings together what is happening, why it may matter, timing, open questions and the next useful investigation, while retaining earlier versions.

- **Context:** Project, scope and public position
- **Priority:** Urgency, confidence and gaps
- **Next steps:** Questions for a person to investigate

### Salesforce work

People review the brief and choose the work to own.

The native relationship runs Account → Market Initiative → Market Signal, then to a human-assigned Task or initial Opportunity with its research context.

- **Review:** Inspect evidence and optionally assess
- **Relationships:** Account → Market Initiative → Market Signal
- **Actions:** Assign a Task or create an Opportunity
- **Authority:** Human owners and commercial fields

### Wider sales process

Owned work can continue through the company’s normal sales process.

The sales team owns the pitch, proposal, negotiation and potential contract; Radar supplies the research context behind the initial handoff.

- **Continuation:** Pitch → contract
- **Ownership:** The sales team manages later stages
- **Context:** The brief remains linked to the handoff

## An illustrative brief

### Riverbend 115 kV upgrade

FICTIONAL EXAMPLE · NOT A LIVE RECORD

A utility capital plan identifies a new line and substation bay; a tender requires a pre-bid site visit; an addendum changes the access-road scope.

**Priority considerations:** Confirm the site-visit requirement and revised civil scope before committing estimating time.

- **Capital plan:** A utility plan identifies a new 115 kV line and substation bay.
- **Tender requirement:** The tender requires a pre-bid site visit before submission.
- **Scope addendum:** An addendum changes the access-road and civil-work scope.
- **Work package:** 115 kV transmission line, substation bay and civil access
- **Procurement step:** Pre-bid site visit required before tender submission
- **Uncertainty:** Confirm the revised access-road scope and estimating implications
- **Assignment:** Estimating lead investigates the open requirement
- **Trace:** Source link, captured version and brief history remain connected

## Illustrative routes

### Build a brief

1. **Public sources:** Find and check public pages
2. **Signals:** Accumulate supported signals
3. **Maintained briefs:** Build the maintained brief
4. **Salesforce work:** Review and choose

### Update the picture

1. **Salesforce work:** Request a focused check
2. **Public sources:** Recheck approved sources
3. **Signals:** Add only supported change
4. **Maintained briefs:** Update the brief version

### Investigate

1. **Maintained briefs:** See the open question
2. **Salesforce work:** Review and assign a Task

### Pursue

1. **Maintained briefs:** Read the supporting context
2. **Salesforce work:** Create an initial Opportunity
3. **Wider sales process:** Continue to pitch and potential contract

### Keep watching

1. **Salesforce work:** Choose to keep watching
2. **Maintained briefs:** Keep the current context
3. **Public sources:** Request a later on-demand check

## Decisions locked

| Axis | Decision | ADR |
|---|---|---|
| Where it fits | A research layer before and alongside commercial work. Business development reads the brief; a named colleague investigates a Task; an Opportunity owner takes responsibility for an initial pursuit. | PRODUCT\_SPEC.md; SALESFORCE\_SPEC.md |
| Current scope | A proof of concept with a small configured set of initiatives and on-demand checks of approved public HTML. Sources, dates, uncertainty and history stay visible. The map describes the approved workflow, not current service availability. | PRODUCT\_SPEC.md; ARCHITECTURE.md |
| A human next step | Reading, assessing, accepting evidence and creating commercial work are separate actions. Research never makes those decisions for a person. | PRODUCT\_SPEC.md; BRIEF\_IMPLEMENTATION\_CONTRACT.md |
| An illustrative project | Follow an illustrative utility infrastructure project from a published procurement notice to an investigation Task and a possible Opportunity. A later project hold changes the research while preserving what the team knew when it acted. | Atlas example; representative information only |
| Possible next steps | Scheduled checks, wider approved source coverage and richer public-source context could extend the tool. These are future possibilities, with scope and operating choices still to be agreed. | RESEARCH\_DESIGN.md; not current capabilities |

## Cost model

This introduction is a static website. Exploring it does not request research or call a model.
The research service uses bounded source checks and model calls. Its operating limits are separate from this atlas.
## Deep dives

The map describes the approved proof-of-concept workflow. It is not a live status display. The project in the walkthrough and every information example are illustrative, not records from a client system.

## Further reading

1. **Start with a useful brief** — Understand the project before deciding how much attention it deserves. _(adds team, brief)_
2. **Follow the evidence** — A useful brief lets you see what its claims rest on. _(adds sources, evidence, findings)_
3. **Choose your next step** — Turn understanding into a deliberate human next step. _(adds assessment, task, opportunity)_
4. **Ask for an update** — A focused request checks what is known and looks for specific gaps. _(adds check, search)_
5. **See how research becomes a brief** — Supported facts, careful comparison and checked publication keep the brief useful. _(adds process, history)_
6. **Keep decisions in context** — The team can see both the latest research and what it knew when it acted.
7. **The whole system** — Public information becomes useful research; people choose what happens next.

## Structures

### Public information

#### SP · Public pages

**In one line.** Approved public pages provide the project information Radar can check.

**What it does.** Project updates, procurement notices and published requirements can contain useful signals about an initiative. The current tool reads approved public HTML pages. A document may contain several distinct events or conflicting dates; the original wording remains important.

**How it's built.** Initiative-scoped source watches and a source policy control canonical HTTPS retrieval. PDF files, authenticated portals and form submissions are outside the current scope. Each allowed retrieval records when it occurred and what the source returned.

**Steps in execution.**

1. **Select approved sources** — Use the sources configured for the selected initiative.
2. **Read the actual page** — Retrieve the allowed canonical HTML, rather than treating a search snippet as evidence.
3. **Keep the wording** — Retain the passage and date precision, including uncertainty or contradictions.

**Questions.**

- ~~**Q-SP1** Does Radar cover every public project?~~ ✓ No. The proof of concept checks a small configured scope; coverage must be stated explicitly. \(2026-09-05\)

#### SS · Source search

**In one line.** Focused search looks for a missing update or an unresolved question.

**What it does.** Radar first checks the sources it already knows. If a specific gap remains, it can look for an addendum, award, correction or project hold. A search result is a lead to inspect, not a verified finding.

**How it's built.** Exa sits behind the discovery adapter. The bounded Luna tool loop can request search\_sources and fetch\_source. Search metadata never bypasses the source policy: only an approved canonical page can be retrieved and retained as evidence.

**Steps in execution.**

1. **Name the gap** — Use the initiative and the research question to focus the search.
2. **Find candidate pages** — Return relevant links and descriptive metadata.
3. **Check permission and relevance** — Only allowed, relevant pages move on to retrieval; other links remain leads.

**Questions.**

- **Q-SS1** Could a team search across more organisations or regions? → _Possible extension: agree the scope, source permissions and coverage expectations before broadening discovery._

### Research service

#### RC · Research check

**In one line.** A person requests a bounded check for updates to an initiative.

**What it does.** Check for updates starts from an initiative in Salesforce. The request records its progress, checked sources and outcome. Live checks use current permitted sources; Replay uses prepared, saved evidence. New findings, no change, incomplete coverage and failure are different outcomes.

**How it's built.** The native action creates a Research Run. A Cloudflare Worker checks the queue every minute and dispatches a durable Workflow. D1 records the run, observations and delivery state. This dispatch schedule does not automatically monitor the portfolio. Duplicate requests and stale deliveries are guarded.

**Steps in execution.**

1. **Request in Salesforce** — Select an initiative, choose the explicit mode and optionally add a focused question.
2. **Queue and run** — Validate the request and available allowance, then start the hosted workflow.
3. **Show progress and coverage** — Keep waiting, unchanged, partial and failed outcomes visible; a failed attempt is not a successful check.
4. **Recover safely** — Reconcile unfinished delivery without duplicating findings. A failed Live check never silently becomes Replay.

**Questions.**

- **Q-RC1** Can updates run on a schedule without a person asking? → _Possible extension: agree which initiatives to monitor, the cadence and the operating allowance. Current research is on demand._

#### RP · Research process

**In one line.** Radar turns captured passages into supported findings and a useful brief.

**What it does.** The process separates what a source says from what it might mean for the initiative. It checks dates, scope and supporting passages, keeps contradictions visible and compares new facts with the previous brief. A changed page alone does not mean the business situation changed.

**How it's built.** Application-controlled TypeScript sequencing surrounds one bounded OpenAI gpt-5.6-luna tool loop at low reasoning effort. Adapters handle retrieval, extraction and synthesis; application code validates evidence and controls writes. Salesforce receives candidate findings, an immutable run snapshot and then the current brief through ordered, checked delivery.

**Steps in execution.**

1. **Gather and capture** — Recheck approved known pages before searching for specific gaps. Save allowed source content.
2. **Extract supported claims** — Identify source passages, events, dates and work-package scope; retain uncertain or conflicting claims.
3. **Validate and relate** — Check exact support and conservatively relate findings to the initiative. A model suggestion is not human acceptance.
4. **Compare and synthesise** — Compare supported facts with the exact prior Salesforce brief. Publish a new version only for substantive changes.
5. **Deliver and confirm** — Publish findings and the brief snapshot to Salesforce, then confirm matching delivery. If synthesis fails, keep the prior brief and expose incomplete coverage.

**Questions.**

- ~~**Q-RP1** Does the AI decide whether the company should bid?~~ ✓ No. The service proposes research. A person assesses relevance and chooses any commercial action. \(2026-09-05\)

### Evidence & history

#### EL · Evidence library

**In one line.** Saved source versions preserve what was actually read.

**What it does.** The library keeps the captured page, retrieval time and supporting passage behind a finding. A later source update creates a new version rather than rewriting the old evidence. Someone can follow a brief back to its original support.

**How it's built.** Cloudflare D1 stores source identities, immutable retrieved documents and normalised text, with hashes and evidence locators. Search snippets are not acceptance evidence. The public atlas contains representative examples only; it is not connected to this store.

**Steps in execution.**

1. **Save a source version** — Retain the captured content and when it was retrieved.
2. **Locate the support** — Link a claim to the exact passage and retain original date wording.
3. **Keep prior versions** — Preserve the evidence even when the source or the current interpretation changes.

**Questions.**

- ~~**Q-EL1** Is a saved capture the same as a fresh check?~~ ✓ No. Replay keeps its original capture provenance, and cached interpretation remains labelled as reused work. \(2026-09-05\)

#### SF · Supported findings

**In one line.** A finding records a specific observation and the evidence supporting it.

**What it does.** One notice may produce several findings: a meeting requirement, a submission deadline or a date conflict. These are observations about an initiative, not extra sales leads. People can inspect them and separately accept, reject or defer evidence when appropriate.

**How it's built.** D1 stores assertions, candidate identities and source relationships. Salesforce Market Signal records display the candidate findings. Human evidence review stays separate from a brief assessment and commercial qualification. Replaying a saved result preserves its identity and prior review.

**Steps in execution.**

1. **Read the observation** — See the specific event or issue, its scope and its uncertainty.
2. **Check its support** — Open the source context and the passage behind the claim.
3. **Review evidence if useful** — Accept, reject or defer explicitly. This does not create an Opportunity or record a brief assessment.

**Questions.**

- ~~**Q-SF1** Must every finding be accepted before the team can act?~~ ✓ No. Investigation can begin with uncertain evidence. Initial Opportunity qualification requires readable current research and a non-rejected supporting finding, followed by a person's confirmation. \(2026-09-05\)

#### BH · Brief history

**In one line.** Versioned briefs keep earlier decisions connected to what was known at the time.

**What it does.** A new finding may change the brief. Earlier assessments and handoffs retain the exact version they used, so a later hold does not erase the context behind an earlier action. New research can prompt another human decision.

**How it's built.** Cloudflare D1 keeps immutable research brief versions and evidence links. Salesforce Research Run snapshots retain the delivered brief content, while the initiative points to its current version. Assessments and Task/Opportunity handoffs reference those versions; their human history remains in Salesforce, outside this research store and model input.

**Steps in execution.**

1. **Preserve the brief version** — Keep its findings, source references and coverage together.
2. **Pin the human context** — An assessment, Task or Opportunity refers to the version visible when the person acted.
3. **Show what changed** — Publish substantive research updates while retaining the previous versions and decisions.

**Questions.**

- ~~**Q-BH1** What if an update is incomplete?~~ ✓ Keep the previous brief, expose the new validated findings and show the incomplete update. A failed check must not imply fresh coverage. \(2026-09-05\)

### Your team in Salesforce

#### IB · Initiative brief

**In one line.** A maintained brief gives the team a source-linked view of an external project or programme.

**What it does.** Open the Salesforce Overview to find the initiatives already in Radar. Each brief brings together scope, public developments, important dates, requirements and uncertainties. Follow What changed or a source reference when you want the supporting detail.

**How it's built.** The native Market Initiative record holds the current generated brief and its Account context. Evidence and Research Run records provide source and version navigation. Generated research fields are separate from human judgments. There is no general manual initiative-entry or broad-search screen in this proof of concept.

**Steps in execution.**

1. **Browse initiatives** — Start with a useful summary, key finding and source context in Salesforce.
2. **Understand the project** — Read the brief, public timing and specific uncertainties.
3. **Follow the evidence** — Inspect the supporting findings or compare the latest substantive change.

**Questions.**

- ~~**Q-IB1** Is an initiative already a sales Opportunity?~~ ✓ No. An initiative is the external project or programme being researched. An Opportunity is a person's decision to begin a commercial pursuit. \(2026-09-05\)

#### YT · Your team

**In one line.** People decide what deserves attention and who should take the next step.

**What it does.** Business development uses the brief to understand emerging work. A colleague can investigate a specific uncertainty, and a named owner can qualify a commercial pursuit. Research is useful before anyone takes formal ownership of an Opportunity.

**How it's built.** Users work through their own Salesforce access. Native actions record the person and relevant brief context. The runtime cannot accept evidence, assess a brief for someone, create Tasks or Opportunities, or change commercial fields. Capacity and eligibility are not inferred from public project information.

**Steps in execution.**

1. **Understand** — Read the current brief and its limitations.
2. **Choose** — Optionally assess, investigate with a Task, create an Opportunity or keep watching; these are different choices.
3. **Take responsibility** — Creating owned work names a person and records the research context behind the action.

**Questions.**

- **Q-YT1** Could Radar use a company capability profile? → _For a future authorised customer deployment only. This demo uses public project sources and needs no private-company inputs or capability-profile approval. Public context would still not prove current capacity or bid eligibility._

#### BA · Optional assessment

**In one line.** A person can record their response to the exact brief they read.

**What it does.** Review brief offers Worth exploring, Needs clarification, Keep watching and Not relevant, with an optional shared comment. This records one person's judgment; it is neither team consensus nor evidence acceptance. Reading or creating work does not require this step.

**How it's built.** The native Salesforce action appends the actor, time, response and exact brief snapshot. Independent people can assess the same version. Later research retains their earlier responses and shows when they precede a substantive update. Brief comments remain Salesforce-only.

**Steps in execution.**

1. **Read the brief** — Start from the current delivered research and its source context.
2. **Choose a response** — Record your own assessment, with no preselected answer.
3. **Keep its context** — Save the exact version and an optional comment; other people's assessments remain independent.

#### IT · Investigation Task

**In one line.** A Task turns a question into a specific piece of owned work.

**What it does.** Ask a named colleague to clarify a requirement, check eligibility or investigate a disputed date. Set an internal due date and retain the relevant brief and finding. A Task can investigate candidate, deferred or rejected evidence without accepting it.

**How it's built.** A person creates a standard Salesforce Task with the initiative and exact brief/finding references. Immutable handoff context is kept in the initiative's Task handoff history; the Task description is an editable preview. Repeated submission is guarded. Public project dates never become an internal deadline automatically.

**Steps in execution.**

1. **Define the question** — Use the brief or a particular finding to explain what needs checking.
2. **Name an owner and due date** — Make a deliberate internal assignment.
3. **Carry the context** — Link the Task to the initiative and preserve the brief version used at handoff.

#### OP · Opportunity

**In one line.** An Opportunity starts a human-authorised commercial pursuit in Salesforce.

**What it does.** When someone chooses initial qualification, they create a normal Opportunity with an owner, stage, internal close date and next step. It carries the research context and can have an optional follow-up Task. The underlying initiative remains available for later checks.

**How it's built.** The native action requires readable current research, a non-rejected primary finding and final human confirmation. It retains an immutable handoff snapshot and links to the initiative. One current Radar Opportunity per initiative is the demo limit; a repeat returns the existing record unchanged. Public values never automatically set Amount or Probability.

**Steps in execution.**

1. **Make the qualification decision** — Select current supporting research and explicitly choose to create the Opportunity.
2. **Set commercial fields** — Choose an owner, open stage, internal close date and next step; public estimates are only context.
3. **Keep the connection** — Retain the handoff snapshot and link to current research. Later brief changes do not silently change the Opportunity.
4. **Add follow-up if useful** — An optional Task is a separate action; if that step fails, the created Opportunity remains intact.

## Flows (representative packets)

Payload shapes are what the design implies, not measured traffic.

### User journey

| # | From → To | Packet | Representative payload |
|---|---|---|---|
| 1 | brief → team | Read the brief | \{"Project":"Illustrative grid upgrade","Context":"A procurement notice adds a submission deadline","Status":"Example only; not a live finding"\} |
| 2 | team → findings | Inspect the support | \{"Question":"What exactly does the notice require?","Action":"Read the finding and its source passage"\} |
| 3 | findings → team | Understand the evidence | \{"Finding":"The notice gives a submission deadline","Caveat":"The notice does not establish our eligibility or capacity"\} |
| 4 | team → assessment | Option: assess | \{"Optional response":"Worth exploring","Context":"This person's response to this brief version"\} |
| 5 | team → task | Option: investigate | \{"Question":"Clarify the published requirements","Owner":"A colleague chosen by the user","Due date":"Chosen by the user"\} |
| 6 | team → opportunity | Option: qualify | \{"Decision":"Begin initial commercial qualification","Owner and stage":"Chosen by the user","Context":"The exact brief and a non-rejected primary finding"\} |

### Research cycle

| # | From → To | Packet | Representative payload |
|---|---|---|---|
| 1 | team → check | Request an update | \{"Scope":"The selected initiative","Mode":"Live for this illustrative research path","Question":"Has the project position changed?"\} |
| 2 | check → sources | Check known pages first | \{"Source":"An approved project page","Purpose":"Recheck known evidence before looking for gaps"\} |
| 3 | sources → evidence | Capture allowed HTML | \{"Saved":"Page content, retrieval time and source identity","Support":"Original source wording and precise passages"\} |
| 4 | evidence → process | Extract known-source facts | \{"Input":"Captured source passages","Checks":"Dates, scope, exact support and initiative relationship"\} |
| 5 | process → search | If needed: search a gap | \{"Question":"Is there a published addendum or project hold?","Scope":"Bounded discovery for this initiative"\} |
| 6 | search → sources | Qualify discovered links | \{"Result":"A candidate source link, not accepted evidence","Next":"Fetch and capture only if the page is permitted"\} |
| 7 | process → findings | Publish supported findings | \{"Result":"Validated candidate observations","Review":"Human review remains separate"\} |
| 8 | process → history | Save a changed brief | \{"Condition":"Substantive supported facts changed","If incomplete":"Preserve the prior brief and show incomplete coverage"\} |
| 9 | history → brief | Deliver the current brief | \{"Publication":"Findings, immutable snapshot and current brief are checked together","Result":"Source-linked research visible in Salesforce"\} |

### Evidence & history

| # | From → To | Packet | Representative payload |
|---|---|---|---|
| 1 | sources → evidence | Preserve the source | \{"Example":"A later notice says the project is on hold","Saved":"The original passage and capture provenance"\} |
| 2 | evidence → findings | Link the observation | \{"Finding":"A project hold has been published","Meaning":"A supported observation; not an automatic commercial decision"\} |
| 3 | findings → history | Support a new version | \{"Earlier brief":"Procurement notice and a question about requirements","Updated brief":"Later hold, with its source and uncertainty"\} |
| 4 | history → brief | Show what changed | \{"Current view":"The new brief explains the hold","History":"The previous brief stays available"\} |
| 5 | brief → team | Reconsider the next step | \{"Choice":"A person can reassess or change their commercial plan","Boundary":"Research does not change an Opportunity or Task for them"\} |
| 6 | history → assessment | Reference assessed brief | \{"Reference":"The exact brief the person assessed","Preserved":"Their original response and time","Storage":"Human assessment and handoff history remains in Salesforce; only the brief reference is shown"\} |
| 7 | history → task | Reference Task brief | \{"Reference":"The brief and finding at handoff","Preserved":"Immutable Salesforce handoff context","Storage":"Human assessment and handoff history remains in Salesforce; only the brief reference is shown"\} |
| 8 | history → opportunity | Reference pursuit brief | \{"Reference":"The research used for qualification","Preserved":"The original handoff snapshot; commercial fields remain human-owned","Storage":"Human assessment and handoff history remains in Salesforce; only the brief reference is shown"\} |

## Questions — index

Reference by ID. ✓ resolved (with date) · otherwise open.

- ~~**Q-SP1**~~ (SP) ✓ No. The proof of concept checks a small configured scope; coverage must be stated explicitly. \(2026-09-05\)
- **Q-SS1** (SS) Could a team search across more organisations or regions? → Possible extension: agree the scope, source permissions and coverage expectations before broadening discovery.
- **Q-RC1** (RC) Can updates run on a schedule without a person asking? → Possible extension: agree which initiatives to monitor, the cadence and the operating allowance. Current research is on demand.
- ~~**Q-RP1**~~ (RP) ✓ No. The service proposes research. A person assesses relevance and chooses any commercial action. \(2026-09-05\)
- ~~**Q-EL1**~~ (EL) ✓ No. Replay keeps its original capture provenance, and cached interpretation remains labelled as reused work. \(2026-09-05\)
- ~~**Q-SF1**~~ (SF) ✓ No. Investigation can begin with uncertain evidence. Initial Opportunity qualification requires readable current research and a non-rejected supporting finding, followed by a person's confirmation. \(2026-09-05\)
- ~~**Q-BH1**~~ (BH) ✓ Keep the previous brief, expose the new validated findings and show the incomplete update. A failed check must not imply fresh coverage. \(2026-09-05\)
- ~~**Q-IB1**~~ (IB) ✓ No. An initiative is the external project or programme being researched. An Opportunity is a person's decision to begin a commercial pursuit. \(2026-09-05\)
- **Q-YT1** (YT) Could Radar use a company capability profile? → For a future authorised customer deployment only. This demo uses public project sources and needs no private-company inputs or capability-profile approval. Public context would still not prove current capacity or bid eligibility.

## What the platform gives vs what we own

**Platform gives:** Cloudflare hosts the research workflow; D1 stores captured evidence, findings, brief versions and run history. Salesforce stores the delivered research view, human assessments, Tasks and Opportunities.

**We own:** Radar connects source gathering, supported findings, maintained briefs and traceable human handoffs. People remain responsible for business judgment.

## How this file is maintained

Generated from docs/atlas/data.json by node docs/atlas/build.mjs, which also builds the interactive atlas (`atlas.html`, published at https://opportunities-radar.pages.dev/). Edit the data file and rebuild; publish only within the authorized destination and audience. Do not edit generated files by hand.