oxFlow Wiki

Anomaly Review

7 min read

Three-layer check pipeline that flags issues before submission. Each layer runs independently and feeds into the same Anomaly Dashboard (view 15). Estimators and Lead Estimators triage flags, resolve or dismiss them per Item, and sign off.

Primary view: Anomaly Dashboard (view 15); entry points across Worksheet Editor (view 6) and Estimate Editor (view 5) Related entities: Reference Rate · Worksheet · Item · Resource · Program & Task · Price Book

1. The three layers

LayerMethodMilestoneTrigger
Layer 1Deterministic rule checksAlphaOn every Anomaly Review run
Layer 2Reference Rate matchingAlpha (rules-first) · Release (AI-assisted)On every run
Layer 3Historical AI comparisonReleaseOn every run

All three write into the same flag list — filterable by layer, severity, target entity, and status (open / resolved / dismissed).

2. Flow

 Estimator clicks
 "Run Anomaly Review"
 │
 ▼
 ┌─────────────────────────────────┐
 │ Anomaly Review engine │
 └──────────────┬──────────────────┘
 │
 ┌───────────────────┼───────────────────┐
 ▼ ▼ ▼
 ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
 │ Layer 1 │ │ Layer 2 │ │ Layer 3 │
 │ (deterministic) │ (Reference │ │ (historical │
 │ │ │ Rate) │ │ AI) │
 └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
 └────────────┬──────┴───────────────────┘
 ▼
 ┌──────────────────────┐
 │ Anomaly Dashboard │
 │ (filterable flags) │
 └──────────┬───────────┘
 │
 ┌──────────────┼──────────────┐
 ▼ ▼ ▼
 Jump to source Resolve Dismiss
 (Estimate/ (fix the (acknowledge;
 Worksheet/ underlying flag persists
 Price Book / issue) but marked
 Program linker) accepted)
 │
 ▼
 Every Item's flags are resolved
 or dismissed → Lead Estimator
 marks Item as Reviewed
 │
 ▼
 When every Item is Reviewed →
 Estimate auto-transitions to
 Reviewed

3. Layer 1 — Deterministic rule checks

Rule-based, predictable, fast. No ML or heuristics. All fire on every Anomaly Review run.

Representative checks (non-exhaustive):

3.1 Structural / data integrity

  • Missing Unit on Item or Resource — both require a Unit.
  • Schedule Item nested under Schedule Item — violates nesting rules.
  • Heading or Item depth exceeded — more than 5 levels.
  • Empty Worksheet + no plug_rate — Item is Unpriced; blocks Submit.
  • Plug rate set AND Worksheet cost-contributing children — violates mutual exclusion (should be auto-prevented, but flagged if encountered).
  • Required Code (Workcentre / Activity Code) missing — soft flag in Estimate; hard block on Cost Management export.

3.2 Snapshot divergence

  • Worksheet Resource rate differs from Resource’s current rate — surfaces post-Adjudication, post-bulk-override, or post-direct-edit on a Resource. Push-through action available.
  • Worksheet Resource flags / modifier defaults differ from Resource — same mechanic.
  • Worksheet Recipe snapshot differs from current Recipe — analogous.
  • Bulk-override inconsistency — after an “Apply to this Estimate” override, new drag-ins of the same Resource snapshot from the original Price Book rate (see rate-edit-mechanics.md §3 Anomaly note).

3.3 Resource Type-specific checks (Resource spec §4)

  • Labour — missing region tag / missing rate tier
  • Material — missing cartage allocation / high wastage without approval
  • Plant — no operator linked / missing hire term
  • Subcontract — missing scope clarity / missing insurance clause
  • Other — no type-specific checks

3.4 Program-linked checks

  • Production Rate mismatch — Item declares a Production Rate Variable; linked Task duration + Item quantity implies a different rate. Estimator reviews and confirms or adjusts (Program & Task spec §7).
  • Orphaned Program Task link — on re-upload, a previously-linked Task no longer present in the new Tender Program version.
  • Parse failed — Tender Program parse_status = failed; file needs re-upload.
  • Item has Production Rate logic but no Tender Program uploaded — informational only.

3.5 Unit-reconciliation heuristic

  • Worksheet Resource unit mismatch with Item unit expectation — e.g., Item is priced per m³ but a Resource contributing the bulk of cost is priced per hour without a clear conversion path. Heuristic 🟡 — not a simple “units differ” check; full heuristic TBD.

3.6 Commercials-gate checks

  • Item is Unpriced or Plugged on Submit — blocks Publisher Publish. Anomaly list is surfaced as the blocking reason.

4. Layer 2 — Reference Rate matching

Anchor layer for rate-based outlier detection against an admin-defined benchmark library (Reference Rates are manual benchmarks).

4.1 Rules-first (Alpha)

Matching criteria:

  1. Unit match — Item’s Unit = Reference Rate’s Unit (required).
  2. Categorization scope — if the Reference Rate has categorization_option_id, the Item must carry that Categorization Option.

When both match and the Item’s unit rate falls outside the Reference Rate’s range / tolerance, a firm anomaly flag is raised with a deterministic explanation.

Rate specification on a Reference Rate is either:

  • Point rate + optional tolerance (e.g., $500/m³ ±5%)
  • Range (e.g., $450–$550/m³)

Multiple Reference Rates can match one Item — all are surfaced.

4.2 AI-assisted (Release)

When an Item isn’t matched via rules-first matching (typically untagged / missing Categorization), the AI layer:

  • Semantically matches the Item’s description against the Reference Rate library.
  • High-confidence matches → firm flag (as if rules-first had matched).
  • Low-confidence matches → “possible anomaly” — estimator acceptance or dismissal feeds future matching.
  • Plain-English explanation with cross-references.

5. Layer 3 — Historical AI comparison (Release)

Distinct mechanism — not a Reference Rate versioning feature. Uses:

  • Archived Price Books (Benchmark migration provides the seed history)
  • Completed estimates (Won / Lost / Archived)

Surfaces Items whose unit rates materially differ from comparable historical items. Each flag includes:

  • The comparable historical entries
  • Market or project-context explanation
  • Plain-English rationale

Estimator can accept, dismiss, or drill into the historical entries.

6. Flag lifecycle

StateMeaning
OpenFlag is active and unresolved
ResolvedThe underlying condition has been corrected (e.g., Unit added, snapshot pushed through, plug_rate cleared)
DismissedEstimator acknowledged the flag intentionally (“this outlier is correct”)

Audit trail: resolution / dismissal records user, timestamp, optional note.

Re-evaluation: flags are re-computed on every Anomaly Review run. A flag that was dismissed may re-appear if the underlying data changes again (e.g., another rate edit), and the dismissal decision needs to be revisited.

7. Anomaly Dashboard interactions

  • Summary cards per layer — counts, severity distribution.
  • Flag list — filterable by layer, severity, entity type, Item, status, detected date.
  • Per-flag actions:
  • Jump to source — routes to the appropriate view (Estimate Editor, Worksheet Editor, Price Book Editor, Program linker).
  • Resolve — applies the fix inline where possible, or directs the estimator to the fix.
  • Dismiss with note — marks acknowledged; audit trail preserved.
  • Bulk dismiss within a category (e.g., dismiss all snapshot-divergence flags for a specific Resource).

8. Reviewed sign-off interaction

Reviewing an Item requires clearing (or acknowledging) its outstanding flags:

  1. Estimator or Lead Estimator opens an Item (Estimate Editor → Item sidebar or Worksheet Editor).
  2. Outstanding flags are visible in the right rail.
  3. Estimator resolves or dismisses each flag.
  4. Lead Estimator (or Admin) marks the Item as Reviewed.

When every Item in the Estimate reaches Reviewed, the Estimate auto-transitions In Progress → Reviewed.

Cascade reminder: any rate edit after Reviewed drops affected Items back to Priced. Anomaly Review re-evaluates; flags may reappear. Estimate may revert Reviewed → In Progress.

9. Roles

CapabilityAdminLead EstimatorEstimator
Run Anomaly Review✅✅✅
Resolve / dismiss flags✅✅✅
Mark Item Reviewed✅✅❌
Manage Reference Rates library✅✅❌
Override Code-missing hard block (on Cost Management export)❌ (hard block)❌❌

All three roles share triage. Reviewed sign-off is gated to Lead Estimator / Admin.

10. Worked example

Scenario: Estimator runs Anomaly Review on an Estimate a day after a Price Book Adjudication awarded new labour rates.

Flags surfaced:

LayerFlagSource
1Snapshot divergence on 14 Worksheet Resources (Carpenter / Electrician / Plumber)Post-PBA award
1Production Rate mismatch on Item “Earthwork excavation”: declared 140 m³/day but implied 150 m³/dayProgram Task-linked Item
1Plant without operator on Item “Crane hire — 30t”Resource Type-specific check
1Missing Workcentre Code on 3 Itemssoft flag
2Unit rate $620/m³ on “Concrete pier cap” exceeds Reference Rate range $450–$550/m³Reference Rate match

Estimator actions:

  • Opens Anomaly Dashboard; 14 snapshot flags grouped (same Resource set from PBA).
  • Pushes through on all 14 — accepts new rates. Cascade: 11 Items drop Reviewed → Priced.
  • Jumps to Earthwork excavation Worksheet; adjusts declared Production Rate to 150 m³/day or updates Item quantity. Flag resolves.
  • Jumps to Crane hire Worksheet; adds an Operator Resource. Flag resolves.
  • Jumps to the 3 Items with missing Workcentre and assigns the right Code Option. Flags resolve.
  • Reviews the Concrete pier cap anomaly: checks Worksheet build-up, confirms rate is correct for this project’s access constraints, dismisses the flag with note “above-range: constrained-access work; verified with supplier”.
  • Re-runs Anomaly Review — 0 open flags.

Lead Estimator then marks affected Items as Reviewed. When all Items Reviewed → Estimate → Reviewed → ready for Publisher preview and Submit.

Graph View