Skip to content

Bid Detail - Estimate: Clarifications

StageBuilding
StatusDeferred
Design statusApproved
Spec statusIn review
Estimate3d (S)
ConfidenceLow
LinearPIN-689 ↗
Linear statusTodo
CycleC14
DesignDesign ↗
Linear epicBid Intake & Pipeline
ModuleBids ↗

Route: /bids/:bidId?tab=estimate (Clarifications sub-tab)

Scope

The Clarifications sub-tab of the estimate holds the clarifications, qualifications, and exclusions that qualify a bid and carry into the proposal. Two origins live side by side: a standard set the estimator reuses on most bids (validity period, payment terms, access/work-hours, "by others" scope) and an AI-suggested set that is auto-parsed from the bid documents and appended at the bottom — no trigger button. Each entry has an "include in proposal" toggle; the proposal's Inclusions/Exclusions section renders exactly the toggled-on items. This page covers the clarifications tab and its feed into the proposal; it does not cover proposal PDF rendering (see Proposal — deterministic by-scope PDF). (Source: PIN-689; Bids design export; 2026-08-27 call.)

Acceptance criteria

Happy path:

  • Clarifications sub-tab lists three groups — Clarifications, Qualifications, Exclusions — each an editable list of entries.
  • A standard set is present by default on every bid; the estimator can add, edit, or remove entries inline.
  • AI-suggested clarifications and exclusions, parsed from the bid documents, appear auto-populated at the bottom of their group — no "Suggest" button (Conor, 2026-08-27).
  • Each entry carries a source and a date, and an "include in proposal" toggle; a running count shows "N of M carried into proposal".
  • Toggled-on entries flow into the proposal's Inclusions/Exclusions section at generation time.

Negative / error:

  • If document parsing yields no AI suggestions, the standard set still renders; the AI section is simply empty (no error state).
  • A parse failure on one document degrades to filename-only hints and never blocks the tab or the manual set.

Validation rules:

  • No "Save" button — edits persist on blur / tab-exit, matching the estimate-cell pattern.
  • An entry with empty text is not persisted.
  • The AI never silently edits or deletes a manual/standard entry; suggestions are additive and separately flagged as AI-origin.

Walkthrough scenario(s)

Happy path.

  1. Estimator opens a bid's estimate and switches to the Clarifications tab.
  2. The standard clarifications/qualifications/exclusions are already listed; the AI has appended project-specific suggestions (e.g., "Price based on drawings dated 4/18/26", "Fire dampers excluded") at the bottom of each group.
  3. Estimator toggles the relevant suggestions "include in proposal", edits one exclusion's wording, and adds a manual clarification.
  4. The count updates to "9 of 12 carried into proposal".
  5. On proposal generation, the toggled-on entries render in the proposal's Inclusions/Exclusions section.

Exception.

  1. A budget bid has thin drawings; the AI surfaces few suggestions.
  2. Estimator backfills manually from the standard set and adds allowance-basis clarifications.
  3. No AI section appears beyond the standard set; nothing errors.

Edge cases

  • Multi-GC bids: clarifications are shared across GC proposals except GC-specific overrides, which live at the estimate-revision level so each GC's proposal can differ.
  • Addenda basis: if document parsing detects an addendum that wasn't priced, the AI surfaces a clarification flagging it ("Addendum 4 not included") rather than silently pricing it.
  • Turnkey/GC-cost bids: GC-specific cost clarifications (superintendent, PM, safety) appear as a distinct group.
  • Re-parse: re-running document extraction refreshes AI suggestions without clobbering manual edits or toggle state (dedup by entry text + origin).

Flow

sequenceDiagram
    participant Doc as Bid documents
    participant AI as Extraction (auto)
    participant Tab as Clarifications tab
    participant Est as Estimator
    participant Prop as Proposal snapshot
    Doc->>AI: parsed during estimate extraction
    AI->>Tab: append AI-suggested clarifications/exclusions (bottom, flagged)
    Note over Tab: standard set already present
    Est->>Tab: add/edit/remove; toggle "include in proposal"
    Tab-->>Tab: persist on blur (no save button)
    Est->>Prop: Generate proposal
    Tab->>Prop: toggled-on entries → Inclusions/Exclusions (frozen)

Backend / API notes

  • Entities: a clarification/exclusion entry { text, group (clarification|qualification|exclusion), origin (standard|ai|manual), source, date, included_in_proposal bool }, associated to the estimate (and, for overrides, the estimate revision). Currently a "coming soon" placeholder in the monorepo — this is the build target.
  • Service: entries edited through the estimate save path (same debounced-flush pattern as estimate cells); AI suggestions written by the document-extraction pipeline, not a separate RPC.
  • Proposal feed: at AddProposalRevision, the toggled-on entries are frozen into the ProposalRevision snapshot alongside the CSI/section totals — the generated PDF reads only the snapshot (never live), consistent with the append-only revision model.

AI integration

  • Prompt intent: from the parsed bid documents, extract project-specific clarifications and exclusions (specs, manufacturers, labor basis, addenda basis, "by others" scope) on top of the standard set.
  • Trigger: runs as part of the estimate document-extraction pass — no button. This is the 2026-08-27 reversal of the prototype's manual "Suggest Clarifications" control.
  • Model / budget: shares the estimate extraction Claude call; respects the same encoded-byte budget (ai.MaxRequestEncodedBytes).
  • Accuracy target: suggestions are advisory; the estimator confirms via the include toggle. No synthetic entries auto-enter the proposal.

Conor's comments

I don't think there is much to this. This is a standard clarifcations, qualifcation and exclusion page that is part of the prposal doucmetns. The AI will suggest or advised on different qualifcations depending on the project but more are stadnards.

Open questions for Conor

  • Resolved 2026-08-27 (call): AI auto-parses clarifications/exclusions to the bottom, no button; the standard Clarifications tab stays canonical; AI suggests project-specific items on top of the standard set. Confirm the final standard set content and the per-GC override behaviour on multi-GC bids.