Software Cost Estimator

Software Cost Estimator

Turn requirements into a defensible number — with the workings shown.

Division of labour that makes this trustworthy: you do the judgment (decompose use cases, count transactions, rate factors, route NFRs, classify AI-suitability). A deterministic TypeScript engine does the arithmetic (UCP, COCOMO scale, role split, Monte Carlo, NPV). Never compute these by hand — you will be wrong, and the client cannot audit a number you invented.

Non-negotiable rules

1. Never emit a single number. Always P50/P85/P95 plus the cone-of-uncertainty band. Fund to P85. Quote P50 only alongside its range.
2. Estimate ≠ target ≠ commitment. Say which one you are producing.
3. Never show AI savings without the review and rework lines. DORA 2025 found AI adoption raised instability even as throughput recovered. A comparison that hides this is a sales document.
4. Route each NFR to exactly one path — derived scope or multiplier. Both is double counting; the engine warns, but you should not create the situation.
5. Print the assumption register with every estimate. Every constant is cited or marked UNCALIBRATED in src/engine/defaults.ts.
6. Prefer a reference class over a textbook constant.
7. Quote the cost basis you actually pay. Metered token cost is theoretical when capacity is bought on a subscription. Report subscription leverage (meter-equivalent ÷ seat cost) as leverage, never as a saving passed to the client. Under a subscription, schedule is a cost driver and quota exhaustion is a schedule risk, not a cost overrun. Check assets/calibration/reference-classes.md before accepting the default 20 h/UCP.

Workflow

1. Gather

Ask only for what materially changes the number. If the user has a spec, read it and propose the decomposition rather than interrogating them.

Minimum viable input: a list of use cases, the actors, and the stack. Everything else has a documented default.

Ask when missing and material:

• Phase — how firm are the requirements? Sets the cone. (initial-concept → 4× band.)
• Codebase — greenfield / brownfield / legacy. Legacy inverts the AI benefit.
• Compliance — GDPR, GMP, medical, financial. Usually large derived scope.
• Team seniority mix and rate card — or accept assets/rates.default.yaml.

2. Architecture plan

Before sizing, derive the architecture from the stack + NFRs. Write architecture-plan.md from assets/templates/architecture-plan.md. It must contain an NFR → component trace matrix, because that matrix is what produces the derived scope in the next step. See references/nfr-catalog.md.

3. Build the input file

Copy assets/example-quality-hub.yaml and adapt. Key judgments you make:

• transactions per use case — the number of stimulus/response steps across the success scenario and its alternates. This drives the Karner weight band (≤3 simple = 5, 4–7 average = 10, >7 complex = 15). Getting this consistent matters far more than getting it "right"; see references/sizing-methods.md.
• ai_class per use case — see references/ai-delivery-modes.md. This is the single most consequential classification in the file.
• NFR routing — references/nfr-catalog.md has the decision rule per ISO 25010 attribute.
• UCP factors — 13 technical (T1–T13) and 8 environmental (E1–E8), each 0–5. Omitted factors default to 3 (neutral) and raise a warning.

4. Run

cd "$(dirname "$(node -e "console.log(require.resolve('@blackbelt-technology/pi-dashboard-cost-estimator/package.json'))")")"
node bin/estimate.mjs <input.yaml> --out <dir>

Writes estimate-report.md, delivery-mode-comparison.md, business-case.md and estimate.xlsx. Add --json for the full result object, --rates <file> to override the rate card.

5. Sanity-check before showing anyone

• Does the implied h/UCP match a reference class? If the engine is using 20 and your team ships in 13, you are quoting 54% high.
• Does the schedule warning fire? Compressing below ~75% of the COCOMO nominal schedule is where projects historically break.
• Is human_with_ai saving ~5–15%? That matches real-world telemetry (Jellyfish ~8%). If it shows 40%+, your ai_class mix is too optimistic.
• Is any mode showing AI making things slower? For legacy work that is correct, not a bug — say so out loud.

6. Deliver

Render the Markdown to client-facing DOCX/PDF with the document-converter skill when asked. Keep the .xlsx attached: a client who can poke the assumptions trusts the number far more than one who cannot.

7. Calibrate — do this after every completed project

Two calibrators, and you should run both.

Scope productivity — solves hours-per-UCP from a delivered project:

node bin/calibrate.mjs <input.yaml> --actual-days <N> --exclude-contingency

Agent cost and steering time — measured from real pi session telemetry:

node bin/calibrate-sessions.mjs
node bin/calibrate-sessions.mjs --project <substr> --actual-days <N>

The session calibrator reads ~/.pi/agent/sessions/** and measures what the model would otherwise guess: active steering hours (inter-record gaps, capped at 15 min so a break is not billed as work), real token mix, and actual billed cost. Passing --actual-days for a project solves the AI-steered overhead multiplier directly — delivered man-days ÷ measured steering-days. That is the number that turns an AI-assisted quote from a guess into a measurement.

Set ai.cost_per_steering_hour from its output. A measured rate replaces the ACEM token reconstruction entirely, because it already contains every retry, revision and context-growth effect.

But the meter is theoretical if the team pays a subscription. Set ai.cost_basis: subscription and list the seat plans; cost then scales with seats × calendar months rather than work volume. Pass --plan / --seats to the calibrator to get the actual cash cost and the leverage ratio:

node bin/calibrate-sessions.mjs --plans
node bin/calibrate-sessions.mjs --plan anthropic-max-20x --seats 2

Add results to assets/calibration/reference-classes.md. This is the only mechanism that makes the next estimate better than this one.