---
name: bid-evaluator
description: >
  Evaluate tabulated subcontractor bids against specs and drawings — scope
  gap analysis, exclusion risk scoring, award recommendation. Triggers:
  'evaluate bids', 'bid evaluation', 'lowest responsible bidder'.
argument-hint: "<tabulated_bids_dir> [scope_description]"
disable-model-invocation: true
---

# Bid Evaluator

Evaluate tabulated subcontractor bids against construction documents.
This skill does NOT make the award decision — it builds the analytical
foundation so the PE/PM can decide quickly and confidently.

## Pipeline & Disambiguation

```
/bid-tabulator → THIS SKILL → user confirms → /subcontract-writer
```

**This skill requires tabulated bids as input.** If the user has raw bid PDFs that haven't been tabulated yet, stop and ask them to run `/construction:bid-tabulator` first; it is user-invoked only, so you cannot start it from here. It produces the per-bidder JSON files and comparison Excel that this skill consumes.

- User has **bid PDFs** → ask them to run `/construction:bid-tabulator` (data capture), then `/construction:bid-evaluator`
- User has **tabulated bids** and wants analysis → this skill directly
- User says "compare bids" or "buyout" → check if bids are already tabulated; if not, ask them to run `/construction:bid-tabulator` first

## Tier System

- **RIGID**: Output schema, scoring tables, file naming
- **GUIDED**: Dialogue sequencing, scope assembly, scoring thresholds
- **FLEXIBLE**: Bid interpretation, scope coverage, risk assessment

## Required Inputs

1. Tabulated bids (from /bid-tabulator or equivalent)
2. Relevant specification sections
3. Relevant drawing sheets (Claude reviews via vision)
4. Scope context (from user dialogue)

Optional: bid form/ITB, schedule, owner requirements, budget estimate,
past experience with bidders.

---

## Step 1: Scope Assembly

**Complete before analyzing any bids.**

### Mode Detection
Read `.construction/project.yaml` at the project root: present and readable means AgentCM mode (note its `contract_version`), absent means flat-file mode. A listing that shows the file does not decide it: read it.
- **AgentCM mode**: Read each spec section from `.construction/specs/<section>.txt` (`09 65 13` is `09-65-13.txt`; each line starts with its page), listed in `.construction/INDEX.md`: it is the section's text, and a section's pages are never extracted again from the PDF. Never run `pdf_text.py` or `rasterize_page.py` on a section's pages: not to check them, and not inside a page range (`--pages 1,2` where page 2 is a section is one). A read manual's pages in no section (INDEX.md lists them) are read in the PDF, those pages only (`--pages`). Only for a manual INDEX.md lists under "Spec manuals not read", read spec-splitter's `.construction/skills/spec_text/` instead. Use sheet index from `.construction/index/sheet_index.yaml` for drawing identification. Follow `${CLAUDE_PLUGIN_ROOT}/reference/agentcm-mode.md`: which source wins, what a missing file or an empty search means, which file answers what, drawings through `crop.sh`, sheet ids, and how to record a correction of AgentCM's data.
- **Flat File mode**: Discover spec PDFs via `CLAUDE.md` paths or directory search (`Specifications/`, `Specification Sections/`). Read drawing sheets directly from PDF.

### 1a. Spec Review
Extract from each spec section: work included (Parts 1-3), work by
others (GC/NIC/Owner), related section cross-references, performance
requirements, coordination and temporary requirements.

This step is never skipped. The spec sections are the baseline that
SILENT is measured against; a scope sheet lists sections, not their
requirements, and "no drawing review" does not mean "no spec review".
In flat-file mode dump each section's text (TEXT pages in the dump are
read as text; rasterize VISION pages):
```bash
"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/pdf/pdf_text.py" "{section.pdf}"
```
Take the output directly, or, to search a dump more than once, save it with
`--output ".construction/skills/bid-evaluator/text/<section>.txt"`, never in
`/tmp` or any other folder outside the project.

### 1b. Drawing Review
Load `references/drawing-review.md` for guidance on what to look for
per drawing type. Vision-read key sheets to identify scope items,
conditions, and quantities not apparent from specs. Track drawing-
derived items separately — they differentiate thorough bidders.
Offload reference after completing drawing review.

### 1c. User Dialogue
Ask targeted questions to fill gaps documents can't answer. Do not
dump a questionnaire — ask conversationally, skip what you already
know.

**Always ask:** package definition (which specs/drawings), GC-provided
items, bid count and format, drawing confirmation if provided.

**Ask when relevant:** multi-trade splits, alternates/allowances,
qualification requirements, budget reference, schedule constraints.

Confirm assembled scope with user before proceeding.

### 1d. Build Scope Baseline
Produce internal baseline document: items in sub scope (with source),
drawing-identified scope, GC/owner exclusions, allowances, alternates,
qualifications, schedule constraints.

---

## Step 2: Bid Analysis

Load `references/buyout-domain.md` for domain knowledge on bid
language interpretation, common scope splits, red flags, trade-
specific evaluation notes, and non-price factors. Keep loaded
through Steps 2a-2d, then offload.

### 2a. Normalize Pricing
```
Adjusted Base = Submitted Base
              + Excluded spec-required items
              - Included GC-provided items
              + Accepted alternates ± Allowance adjustments
```
Valuation order: other bidder's line item → budget estimate → professional
judgment (flagged) → qualitative risk if unknown.
Document every adjustment. No silent price changes.
Flag unit price outliers (>2x median). Calculate exposure ranges.

### 2b. Scope Coverage Mapping
Map each bidder against every scope baseline item using five statuses:

| Status | Meaning |
|---|---|
| INCLUDED | Explicitly includes |
| EXCLUDED | Explicitly excludes |
| SILENT | Not addressed — **most dangerous** |
| PARTIAL | Includes with limitations |
| DIFFERENT | Offers substitution |

Flag all SILENT items on spec-required scope. Drawing-derived SILENT
items suggest incomplete document review by that bidder.

### 2c. Exclusion Risk Scoring

| Level | Criteria |
|---|---|
| CRITICAL | Spec-required, uncarried, >1% bid or >$5K |
| SIGNIFICANT | Implied by spec/practice, $2K-$5K |
| MINOR | Common GC-provided, <$2K |
| INFO | Clarification only, no cost impact |

### 2d. Qualification & Responsibility
Assess per bidder: bonding, insurance, licensing, experience,
capacity, DBE/MBE, bid completeness.
**Bust detection:** >20-30% below field + scope gaps + incomplete
submission. Flag for verification, never call it a bust.

### 2e. Responsiveness and the Recommendation

- A **curable** defect (addenda not acknowledged; an illegible or missing
  line that reconciles to the stated total; validity shorter than required;
  bond not mentioned where one is required) keeps the bid in the ranking at
  its stated price.
- Recommend the apparent low bidder **conditionally**: each cure is a named
  award condition in `recommendation.conditions` (written addenda
  acknowledgment with no price change; a clean copy of the illegible line;
  a validity extension; a bond commitment). Name the next fully responsive
  bidder as the fallback and state the spread.
- A figure derived for an illegible line is allowed only when it reconciles
  exactly to the stated total, and it is always labelled "derived, confirm",
  never presented as read.
- A **non-curable** defect (budgetary-only pricing; a stale drawing basis the
  bidder has not re-confirmed; SILENT spec-required scope the bidder will not
  carry) makes the bid "not awardable as submitted"; it is ranked but never
  recommended.

---

## Step 3: Output

Build JSON per schema in `scripts/sample_input.json` with the Write tool
(not a shell heredoc, which fails here on an apostrophe, and not a helper
script) as `.construction/skills/bid-evaluator/bid_evaluation.json`: it is
working data, never in the project root. Then run:
```bash
"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_SKILL_DIR}/scripts/export_bid_evaluation.py" .construction/skills/bid-evaluator/bid_evaluation.json "Bid_Evaluation_{package}.xlsx"
```
Run it from the project folder: the workbook is the deliverable and goes in the project root (or the folder the PE names), never under `.construction/`, which macOS and Linux hide.

The script produces 5 sheets: Bid Comparison, Price Summary,
Exclusion Detail, Qualification Summary, Recommendation.

---

## Step 4: Handoff

1. Lead with the recommendation — don't make them hunt for it
2. Highlight items needing PE attention
3. Ask for explicit confirmation: selected bidder, scope adjustments,
   alternates, special conditions

**Do NOT proceed to a subcontract without user confirmation.** `subcontract-writer` is user-invoked only; once the user has confirmed the selected bidder, tell them the next step is `/construction:subcontract-writer` and stop.

---

## Step 5: Write a Finding

Record the evaluation as a finding in `.construction/skills/bid-evaluator/findings/` (both modes):

```bash
"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/graph/write_finding.py" \
  --skill "bid-evaluator" --type "bid_evaluation_complete" \
  --title "Bid evaluation: {scope} — {N} bidders, recommended {company}" \
  --output-file "Bid_Evaluation_{package}.xlsx" \
  --data '{"scope": "...", "bidder_count": N, "recommended": "...", "adjusted_amount": ..., "pe_attention_items": [...]}'
```

---

## Context Needs Chart

| Step | Resource | Load Trigger | Offload After |
|---|---|---|---|
| 1b | `references/drawing-review.md` | Drawing sheets provided | Step 1b complete |
| 2 | `references/buyout-domain.md` | Entering bid analysis | Step 2d complete |
| 3 | `scripts/sample_input.json` | Building output JSON | Step 3 complete |
| 5 | `${CLAUDE_PLUGIN_ROOT}/scripts/graph/write_finding.py` | Step 5 | Step 5 complete |

## Gotchas (measured in eval runs)

- Write JSON and YAML with the Write tool. `cat > file <<'EOF'` failed with "unexpected EOF while looking for matching `'`" whenever the content held an apostrophe (3 of 15 runs, 2026-10-04), costing a turn each time.
- Do not write helper scripts or inline `python -c`, even to assemble your own JSON or to read a PDF; the allowlisted scripts are the toolkit, and the exporters do the arithmetic checks. If the toolkit lacks something you need, say so in the handoff instead (bid-tabulator and subcontract-writer each wrote a helper script in their 2026-10-04 runs; the eval guard blocked both).

## Error Handling

- Uneven formats: note difficulty, don't penalize lump-sum bids
- <3 bids: note limited field, suggest re-bid if appropriate
- Budget mixed with hard bids: segregate with caveat
- Math errors: flag discrepancy, don't correct
- Scope too complex: focus on highest cost-impact items

## What This Skill Does NOT Do

- Contact subs, execute awards, or negotiate pricing
- Replace PE judgment on responsibility
- Produce subcontracts (use /subcontract-writer)
- Perform quantity takeoffs from drawings

## File Safety
Never overwrite an existing bid evaluation. The export script uses `safe_output_path()` which appends `_v2`, `_v3`, etc. automatically.

---

## Allowed Scripts

- `${CLAUDE_PLUGIN_ROOT}/bin/construction-python`
- `${CLAUDE_PLUGIN_ROOT}/scripts/pdf/pdf_text.py` — spec section and bid text (Step 1a)
- `${CLAUDE_PLUGIN_ROOT}/scripts/pdf/rasterize_page.py` — drawing sheets and VISION pages
- `${CLAUDE_SKILL_DIR}/scripts/export_bid_evaluation.py`
- `${CLAUDE_PLUGIN_ROOT}/scripts/graph/write_finding.py`
- `${CLAUDE_PLUGIN_ROOT}/scripts/corrections_append.py` — AgentCM mode: record a correction of AgentCM's data (`reference/agentcm-mode.md`)

No other code: no `python -c`, no helper script. If the toolkit lacks something
you need, say so in the handoff.