/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, run `/bid-tabulator` first to produce the per-bidder JSON files and comparison Excel. This skill consumes that output.

• User has **bid PDFs** → `/bid-tabulator` (data capture) → then offer this skill
• User has **tabulated bids** and wants analysis → this skill directly
• User says "compare bids" or "buyout" → check if bids are already tabulated; if not, start with `/bid-tabulator`

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 `.construction/` directory at the project root.

• **AgentCM mode**: Read specs from `.construction/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:

${CLAUDE_SKILL_DIR}/../../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 /subcontract-writer without user confirmation.**

---

Step 5: Write Graph Entry

If `.construction/` directory exists (AgentCM mode), record the evaluation:

${CLAUDE_SKILL_DIR}/../../bin/construction-python ${CLAUDE_SKILL_DIR}/../../scripts/graph/write_finding.py \
  --type "bid_eva