A snapshot of what’s in the docs today and what still needs to be produced to reach a dev-ready spec.
1. What exists today
Foundation (docs/foundation/)
- Concept Map (
concept-map.md) — five-layer entity map, cardinality reference, self-referential relationships, derived attributes, multi-select attributes, provisional lifecycle states. Paired SVG/Excalidraw diagram. - Business Rules (
business-rules.md) — 123 numbered rules, 88 🟢 locked / 32 🟡 working / 3 🔴 open. Summary table + detailed rationale per rule. - Roles & Permissions (
roles-permissions.md) — three-role model (Admin, Lead Estimator, Estimator); full capability matrix per entity area; gating rules. - Non-Functional Requirements (
nfr.md) — baseline targets across performance, security, collaboration, data lifecycle, training, hosting, accessibility, observability.
Shared reference (docs/other/)
- Glossary (
glossary.md) — full term set including Batch B/C concepts. - Benchmark Migration (
migration-benchmark.md) — entity/field mapping, cutover plan, data cleaning rules, rollback plan. Key decisions locked (Codes naming, rate history via archived Price Books, Output Unit direct-map, Flag/Modifier mappings).
Entity specs (docs/entities/)
All 17 entities have drafted, BR-reviewed, versioned specs:
| Layer | Entities |
|---|---|
| 1 · Work hierarchy | Tender · Estimate · Heading · Item · Worksheet |
| 2 · Building blocks | Resource · Recipe |
| 3 · Pricing & procurement | Price Book · Adjudication · Subcontract Package |
| 4 · Commercials & submission | Commercials |
| 5 · Reference data | Company · User · Unit · Categorization · Codes · Reference Rate · Program & Task |
Flows & IA (docs/flows/) ✅ complete
- Estimator journey (
estimator-journey.md) — 8-stage end-to-end narrative from Tender creation through outcome. - View inventory (
view-inventory.md) — 28 views across global, work hierarchy, pricing & procurement, commercials, building blocks, cross-cutting, and admin. 10 flagged for high-fidelity prototyping. - Navigation map (
navigation.md) — primary sidebar, contextual nav, breadcrumbs, full view-to-view transition map, modal/drawer/full-page conventions, URL schema, empty/error/loading/locked patterns, concurrency affordances. - Lifecycle states (
lifecycle-states.md) — consolidated state machines for Tender, Estimate, Item, Price Book, Price Book Adjudication, Subcontract Package Adjudication, Subcontract Package (derived), Tender Program, Publisher Output + cross-entity cascade table. - Sub-flows (
sub-flows/) — Worksheet build-up, rate-edit mechanics, Price Book Adjudication, Subcontract Package Adjudication, Commercials, Anomaly Review.
Supporting infrastructure
- Docs viewer app (
app/) — self-contained browser for all the specs, with cross-references and auto-generated TOCs. - Per-entity changelogs and open-items (
docs/_internal/changelog/,docs/_internal/open-items/) — one file per entity tracking history and outstanding questions.
2. What’s still open inside the existing docs
Working items to close before (or alongside) downstream work.
Concept map
- Lifecycle state list per entity — currently provisional, needs full sign-off walk-through
- Rule scope polymorphism — clean modelling approach for Rules targeting heterogeneous scope types
- Publisher Output versioning — retain all, or latest only (BR-075 currently says latest)
- Program Task ↔ Item cardinality —
M:Mvs1:Mconfirmation - Worksheet Resource / Worksheet Recipe terminology (BR-045)
Business rules — 🔴 open
- BR-017 — Indirect Cost definition (what qualifies as indirect)
- BR-045 — Worksheet Resource / Recipe naming
Business rules — 🟡 working (need refinement / data)
- BR-001 / BR-002 — Heading & Item depth caps
- BR-023 / BR-026 / BR-027 / BR-028 / BR-029 — Flag + Modifier catalog seeding
- BR-073 — Final list of Rule scope targets
- BR-100 / BR-101 — Tender Program location + Task–Item cardinality
- BR-112 — Unit reconciliation heuristic
- BR-125 / BR-126 / BR-127 / BR-128 — Codes details + enforcement tiers
- BR-142 — MS Project format support (.mpp vs alternatives)
- BR-143 — Workbench integration scope / trigger / error handling
Per-entity open items (docs/_internal/open-items/)
Each entity file lists its own residual questions — mostly small details that flow from the BR items above. Addressed as part of the relevant BR resolution rather than separately.
3. Remaining work — what still needs to be produced
3.1 Prototypes
Purpose: clickable Figma prototypes for the views with the highest misunderstanding risk. Not all views — risk-prioritised build order.
Build order (risk-reduction first):
- Worksheet Editor — highest risk, most novel. Must cover resource drag-drop, variable definition, calculation blocks, content blocks, snapshot divergence indicators, recipe drop-in with input parameters, production rate patterns, rate-edit mechanics (per-instance / bulk / fork).
- Estimate Editor — daily driver. Tree nav, heading/subheading/item hierarchy, sidebar stats, item-type indicators, anomaly badges, Item status surfacing.
- Adjudication (both flavours) — six-step workflow UI shared across Price Book and Subcontract Package Adjudication. Two sub-prototypes with shared layout.
- Commercials rules builder — sequenced rule list, scope picker, Submission Value table with overrides.
- Recipe Builder — similar to Worksheet Editor but Input Parameters and Output Unit up front.
- Price Book Editor — medium-fidelity; simpler than Worksheet Editor.
- Publisher — cover letter, conditions, schedule preview, branding config.
- Program linker — MS Project upload, Task–Item linking UI.
- Anomaly Dashboard — aggregate view of all flags, three-layer structure.
- Admin pages — low-fi; mostly form-and-table shapes (Users, Categorizations, Flag/Modifier Catalogs, Codes, Reference Rates, Content Block Definitions, Branding, Integrations).
Low-fi / spec-only (no prototype):
- Tender / Estimate / Price Book list views — standard patterns
- Xero / M365 sync UIs
- Auth flows
- Audit log views
3.2 PRD & dev handoff
Purpose: consolidate Foundation + Entities + Flows + Prototypes into a dev-team-ready spec.
Deliverables:
- PRD document — goals, scope, features, acceptance criteria, non-goals, risks, open items. Shape dev teams expect.
- Per-feature acceptance criteria — checkable bullet list per feature, tied back to specific business rule IDs.
- API / data contract outline — first-pass REST or GraphQL contract from the domain model; not detailed implementation, but enough for estimating.
- Integration specs — Xero, Microsoft 365, MS Project, Workbench. One per integration covering sync direction, triggers, error handling, data mapping, credentials handling.
- NFR test plan — full test plan built on the
nfr.mdbaseline: load testing, security review, accessibility audit, integration resilience.
4. Sequencing & dependencies
| Work stream | Depends on | Can run in parallel with |
|---|---|---|
| Close open items inside existing docs | — | Prototypes (most items only need resolution, not rework) |
| Prototypes | Flows & IA (now complete) | PRD drafting for settled areas |
| PRD & dev handoff | Prototypes feed in for final acceptance criteria | NFR test plan and API contract can start early |
Critical path: Prototypes (Worksheet Editor first) → PRD consolidation.
Parallelisable:
- NFR test-plan drafting can begin immediately from the existing baseline.
- API contract sketching can start from the concept map ahead of the prototypes.
- Open-items closure can happen alongside prototyping — they feed into the PRD.