Estimate Snapshot

Recommended

• RuntimeOverrides.DECOMPOSITION_PATH — absolute path to the latest decomposition markdown. If absent, attempt to locate most recent under {EXECUTION_ROOT}/_Decomposition/. If still missing, log [WARNING] MISSING_DECOMPOSITION and proceed with degraded ID/path validation.
• RuntimeOverrides.DEPENDENCY_SOURCES — AUTO (default) or explicit paths to dependency registers/snapshots
• RuntimeOverrides.PRICE_SOURCES — list of local files/folders containing basis evidence (quotes, rate tables, historical datasets, parametric models, allowance tables)

Optional

• RuntimeOverrides.OUTPUT_LABEL — short label for snapshot naming (default: AUTO)
• RuntimeOverrides.UPDATE_LATEST_POINTER — FALSE (default) | TRUE
• RuntimeOverrides.FALLBACK_POLICY — STRICT (default) | ALLOW_ALLOWANCE | ALLOW_PARAMETRIC
• RuntimeOverrides.ALLOW_MIXED_METHODS — FALSE (default) | TRUE
• RuntimeOverrides.ROUNDING — NONE (default) | CENT | DOLLAR | project-defined
• RuntimeOverrides.RUN_TIMESTAMP — optional ISO timestamp; else generated at runtime

Runtime overrides

Read boundary

Reads are limited to:

• DECOMPOSITION_PATH (when provided or auto-located)
• {deliverable}/Dependencies.csv for each in-scope deliverable (when DEPENDENCY_SOURCES=AUTO)
• Explicit paths provided in DEPENDENCY_SOURCES
• Explicit paths provided in PRICE_SOURCES (quotes, rate tables, historical datasets, parametric models, allowance tables)
• Decomposition and deliverable metadata needed to resolve IDs

The skill must NOT fetch from the internet. Only local inputs.

Write boundary

Writes are limited to the snapshot folder under {ESTIMATES_ROOT}:

• {ESTIMATES_ROOT}/EST_{OUTPUT_LABEL}_{YYYY-MM-DD}_{HHMM}/ (new folder each run)
• Optionally {ESTIMATES_ROOT}/_LATEST.md pointer (only when UPDATE_LATEST_POINTER=TRUE)

No writes outside ESTIMATES_ROOT. No modification of project truth (deliverable content, lifecycle files, decomposition outputs, dependency registers).

Tool usage

Preferred tools

• tools/validation/validate_enum.py — validate BASIS_OF_ESTIMATE at Step 0 (halt with FAILED_INPUTS if invalid)
• tools/scaffolding/create_snapshot_folder.sh — create the immutable snapshot folder with canonical naming
• tools/scaffolding/update_latest_pointer.sh — update _LATEST.md pointer only when UPDATE_LATEST_POINTER=TRUE

Disallowed behavior

• No writes outside {ESTIMATES_ROOT}
• No modification of any file in deliverable folders, decomposition outputs, dependency registers, or lifecycle files
• No overwriting an existing snapshot folder
• No internet fetching (only local PRICE_SOURCES)
• No treating prior snapshots under _Estimates/ as pricing sources unless explicitly included in PRICE_SOURCES

Method

Step 0 — Resolve tool root + create snapshot folder

1. Resolve tool root to {ESTIMATES_ROOT} (or {EXECUTION_ROOT}/_Estimates/).
2. Validate the brief enum: python3 tools/validation/validate_enum.py BASIS_OF_ESTIMATE {BASIS_OF_ESTIMATE}. If invalid or missing, halt with RUN_STATUS=FAILED_INPUTS.
3. Create the immutable snapshot folder: bash tools/scaffolding/create_snapshot_folder.sh {ESTIMATES_ROOT} EST {OUTPUT_LABEL}.
4. If UPDATE_LATEST_POINTER=TRUE, run bash tools/scaffolding/update_latest_pointer.sh {ESTIMATES_ROOT} {snapshot_folder_name}. If FALSE, do not modify pointer files.

Step 1 — Load decomposition (stable IDs + scope mapping)

1. Read DECOMPOSITION_PATH if provided or auto-locate under {EXECUTION_ROOT}/_Decomposition/.
2. Extract Package IDs, Deliverable IDs, labels, and optional hints (CBSHint, EstimateMethodHint, StageHint, ContextEnvelope) if present. Do not invent hints.
3. If decomposition is missing, record [WARNING] MISSING_DECOMPOSITION in QA and Run_Context.md and proceed best-effort.

Step 2 — Enumerate work items from SCOPE

1. Expand SCOPE into a concrete deliverable list.
2. Produce Scope_Resolved.csv (or a Run_Context.md section) listing DeliverableID, PackageID (if known), Path (if known), InScope=TRUE|FALSE, and notes.

Step 3 — Load dependency evidence (readiness + blockers)

1. If DEPENDENCY_SOURCES=AUTO, read each in-scope deliverable's Dependencies.csv if present.
2. Use dependency evidence to identify prerequisites and information gaps that block meaningful estimating. If EstimateImpactClass is present, use it as a hint only.
3. Emit Blockers.md (or blocker_report.csv) listing unresolved inputs by deliverable with evidence references.
4. Dependencies are NOT pricing evidence — they inform readiness only.

Step 4 — Load pricing sources (basis evidence)

1. Index each entry in PRICE_SOURCES into Source_Index.md with source path, source type (quote, rate table, historical, parametric, allowance), parsing notes, and what it can/cannot support.
2. If PRICE_SOURCES is empty or unusable, do not guess prices — produce TBD amounts with FAILED_INPUTS or WARNINGS per SPEC.
3. Avoid recursive ingestion: do NOT treat prior _Estimates/ snapshots as pricing sources unless explicitly listed in PRICE_SOURCES.

Step 5 — Generate estimate detail (automated)

For each in-scope deliverable:

1. Propose line items (minimum one row per deliverable in Detail.csv unless blocked).
2. Assign WBS_PackageID and WBS_DeliverableID from decomposition when available; otherwise best-effort from scope resolution. Assign CBS from explicit CBSHint, else a deterministic rule documented in Run_Context.md, else TBD.
3. Price per BASIS_OF_ESTIMATE using only PRICE_SOURCES evidence:
   • QUOTE → Method=QUOTE
   • RATE_TABLE → Method=RATE_TABLE
   • HISTORICAL → Method=HISTORICAL
   • PARAMETRIC → Method=PARAMETRIC
   • ALLOWANCE → Method=ALLOWANCE
4. Enforce ALLOW_MIXED_METHODS and FALLBACK_POLICY. If fallback is not allowed and basis evidence is missing, set Amount=TBD and log a QA warning.
5. Populate provenance on every row:
   • SourceRef points to a file + section/row ID, OR to an entry in Decision_Log.md / Assumptions_Log.md.
   • If unknown, use location TBD and flag in QA.
6. Apply the allowance/parametric convention when applicable: Qty=1, Unit=LS, UnitRate=Amount.

Step 6 — Produce rollups + matrices

1. Produce WBS_CBS_Matrix.csv with totals by WBS_PackageID, WBS_DeliverableID, CBS, Currency.
2. Produce Summary.md with: basis + run config (BasisOfEstimate_Used block), totals by package/deliverable/CBS, and key warnings + blockers.

Step 7 — QA + logs

1. Produce QA_Report.md including:
   • schema validity (Detail.csv columns + enum validation)
   • coverage (deliverables covered, missing, blocked)
   • provenance completeness (% rows with non-TBD SourceRef)
   • basis-consistency checks (method mix vs BASIS_OF_ESTIMATE)
   • blocker counts (from dependency evidence when available)
   • "what to fix for a cleaner rerun"
   • a declared RUN_STATUS: OK | WARNINGS | FAILED_INPUTS
2. Produce logs:
   • Decision_Log.md — defaults applied, fallback uses, scope-resolution decisions
   • Assumptions_Log.md — explicit assumptions with IDs
   • Risk_Register.md — optional, only if risks are explicit or implied by missing inputs
   • Change_Log.md — what changed vs a referenced prior snapshot

Outputs

Required snapshot artifacts

• Run_Context.md (brief inputs + resolved defaults + chosen paths)
• Summary.md
• QA_Report.md
• Source_Index.md
• Decision_Log.md
• Assumptions_Log.md
• WBS_CBS_Matrix.csv

Conditional/optional snapshot artifacts

• Detail.csv (recommended; required for full runs where pricing sources support meaningful totals)
• Scope_Resolved.csv (when scope expansion is non-trivial)
• blocker_report.csv or Blockers.md (when dependencies are used)
• Risk_Register.md
• Change_Log.md
• Run_Brief.md (verbatim brief text if provided by invoker; recommended for audit)

BOE.md is NOT required by default. If the invoker explicitly requests a narrative BOE, the skill MAY emit BOE.md, but it must be derived from run inputs and sources only (no invention).

Canonical Detail.csv schema (when emitted)

Mandatory columns: LineID, CBS, WBS_PackageID, WBS_DeliverableID, Description, Qty, Unit, UnitRate, Amount, Currency, Method, SourceRef, Confidence, Notes.

• Method ∈ {QUOTE, RATE_TABLE, HISTORICAL, ALLOWANCE, PARAMETRIC}
• Confidence ∈ {LOW, MEDIUM, HIGH} (see QA_CHECKS for confidence rules)
• Allowance/parametric convention: Qty=1, Unit=LS, UnitRate=Amount

WBS_CBS_Matrix.csv (minimum columns)

WBS_PackageID, WBS_DeliverableID, CBS, Currency, Amount_Total, LineCount, ProvenanceCompletenessPct (optional), Notes (optional)

Run_Context.md (minimum fields)

RunID, AsOf, Scope, ScopeResolvedSummary, BASIS_OF_ESTIMATE, CURRENCY, PRICE_SOURCES, DECOMPOSITION_PATH, DEPENDENCY_SOURCES, FALLBACK_POLICY, ALLOW_MIXED_METHODS, UPDATE_LATEST_POINTER, Rounding, Warnings

Non-negotiable constraints

• BASIS_OF_ESTIMATE enum discipline. Value must be exactly one of QUOTE, RATE_TABLE, HISTORICAL, PARAMETRIC, ALLOWANCE. Any other value is FAILED_INPUTS (fail-fast at Step 0).
• Snapshot immutability. Each run writes a NEW snapshot folder under {ESTIMATES_ROOT}. Never overwrite an existing snapshot folder.
• Write quarantine (tool-root-only). Write ONLY under {ESTIMATES_ROOT}. Never modify deliverable content, _STATUS.md or other lifecycle files, decomposition outputs, or dependency registers.
• Provenance-first. Every priced row in Detail.csv MUST carry a SourceRef (file + section/row ID, or an entry in Decision_Log.md/Assumptions_Log.md) OR explicitly location TBD with a QA warning. Every row also carries Method and Confidence.
• No invention. If a quantity, rate, currency, scope boundary, or dependency claim cannot be substantiated by provided sources, record TBD and surface it in QA. Do not guess.
• Confidence rules. Human-confirmed and vendor-quoted values earn HIGH. Parametric values are MEDIUM or LOW. Never assign HIGH to values derived from a parametric model or allowance table.
• Dependencies are not pricing evidence. Dependency registers inform readiness/blockers only. Unit rates must come from PRICE_SOURCES.
• Avoid recursive ingestion. Do not treat prior _Estimates/ snapshots as pricing sources unless explicitly listed in PRICE_SOURCES.
• Deterministic outputs. Given identical inputs (scope + sources + brief), artifacts should be stable apart from timestamps and ordering normalizations.

QA expectations

• BASIS_OF_ESTIMATE was validated by validate_enum.py before any writes occurred.
• A new snapshot folder exists (even if the run is blocked by missing inputs).
• Required artifacts exist: Run_Context.md, Summary.md, QA_Report.md, Source_Index.md.
• When Detail.csv exists: schema is intact, Method values valid, allowance/parametric convention respected.
• Every priced row has a SourceRef or location TBD. Provenance completeness percentage is reported in QA.
• Method mix is consistent with BASIS_OF_ESTIMATE unless ALLOW_MIXED_METHODS=TRUE or a FALLBACK_POLICY deviation is explicitly logged.
• QA_Report.md declares a RUN_STATUS: OK | WARNINGS | FAILED_INPUTS.
• No files outside {ESTIMATES_ROOT} were modified.