---
name: bid-leveling
description: Level subcontractor or supplier bids line by line against one scope sheet - normalise items, units and quantities, check the arithmetic, flag exclusions, alternates, quantity deviations and unit-price outliers, plug missing items with a labelled rule, and rank the leveled totals. Use when the user receives several quotes or bids for the same package, asks for a bid tab, "cuadro comparativo de cotizaciones", "comparativo de ofertas", "nivelación de propuestas", buyout or subcontractor selection.
---

# Bid leveling

Leveling makes bids comparable on scope. It does not choose the winner.

## Inputs
- The bids (PDF, Excel or email text) and, ideally, the scope sheet the bidders were asked to price (items, units, quantities).
- The plug rule the team accepts: median of the other bids (default), highest bid (conservative), or the team's own estimate.

## Procedure
1. Build the scope sheet if there is none: list every item any bidder priced and ask the user to confirm which items belong to the base scope.
2. Transcribe each bid into the long CSV format: `bidder,item,description,unit,qty,unit_price,amount,status,note` with status `included | excluded | clarify | alternate`. Map each bidder's wording to the scope item numbers and keep their words in `description`. Read exclusions and qualifications pages too: an item marked "by others" is `excluded`.
3. Run `python scripts/bid_level.py bids.csv --scope scope.csv --plug median` (options: `--plug max|estimate|none`, `--estimate estimate.csv`, `--outlier 0.25`, `--qty-tol 0.05`).
4. Read the flags: arithmetic errors, quantity deviations from the scope, unit prices far from the median, items priced outside the scope, duplicates, gaps with no plug.
5. Draft a clarification list per bidder (excluded items, "clarify" items, quantity differences, arithmetic) for the buyer to send.
6. Present the leveled totals with the plug rule stated in the first line, and the non-price factors the team must still weigh: schedule, qualifications, safety record, payment terms, warranty, exclusions.

## Output
- `leveling.md` (totals ranked, line-by-line table, flags) and `leveling.csv` (item x bidder matrix + totals).
- Clarification questions per bidder.

## Never
- Never present a plug as the bidder's price; plugs are labelled and listed.
- Never compare totals when gaps remain without saying the totals are not comparable.
- Never recommend an award on price alone or contact bidders; the buyer decides and sends.