Bid Evaluator

---
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
Check for AgentCM: `.construction/project.yaml` at the project root.
- **AgentCM mode**: Read specs from `.construction/skills/spec_text/{section}.txt`. Use sheet index from `.construction/index/sheet_index.yaml` for drawing identification.
- **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.

### 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.

---

## Step 3: Output

Build JSON per schema in `scripts/sample_input.json`, then run:
```bash
"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_SKILL_DIR}/scripts/export_bid_evaluation.py" input.json output.xlsx
```

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 Graph Entry

If AgentCM is present (`.construction/project.yaml` exists), record the evaluation:

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

Without AgentCM, skip — the Excel workbook is the deliverable.

---

## 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` | AgentCM mode detected | Step 5 complete |

## 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_SKILL_DIR}/scripts/export_bid_evaluation.py`
- `${CLAUDE_PLUGIN_ROOT}/scripts/graph/write_finding.py`