| 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
- Tabulated bids (from /bid-tabulator or equivalent)
- Relevant specification sections
- Relevant drawing sheets (Claude reviews via vision)
- 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
- Lead with the recommendation — don't make them hunt for it
- Highlight items needing PE attention
- 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_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": [...]}'
If no .construction/ directory exists, 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 | ../../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_SKILL_DIR}/../../bin/construction-python${CLAUDE_SKILL_DIR}/scripts/export_bid_evaluation.py${CLAUDE_SKILL_DIR}/../../scripts/graph/write_finding.py
