Skip to content

01 — Product & Domain Primer

Plain-language grounding in what you're testing. Read this once, end to end. It gives you the mental model everything else hangs on.

1. What is Cara?

Cara is the product — its full name is "Cara Construction Intelligence." The AI assistant inside the product is also called Cara (you'll see it as "Cara Copilot" and the "Cara Hub"). The company it's built for is HVAC Construction Inc. / Pinley Mechanical — a mechanical and HVAC construction contractor. In construction terms, Pinley is usually a subcontractor (a "sub"): a specialist trade company that bids to do the mechanical/HVAC/plumbing/electrical scope of a larger building project, working under a General Contractor (GC).

Naming note (you will see this in old tickets and docs): the brand is Cara. Earlier names still linger in older Linear tickets, meeting notes, and a few code comments — "Kara" (the original "Kara Construction AI") and "Kera" (a typo/mis-transcription that crept into some planning docs). They all mean Cara. If you see "Kara"/"Kera" anywhere, read it as "Cara."

Before Cara, Pinley ran the business across spreadsheets, email, SharePoint folders, and separate tools. Cara pulls the whole job lifecycle into one system:

  1. Win the work — take in bid invitations, estimate the cost, send quotes to vendors, produce a proposal, and (hopefully) get awarded the job.
  2. Run the work — once awarded, a bid becomes a project: track daily field activity, questions to the GC (RFIs), material approvals (submittals), scope/price changes (change orders), and billing.
  3. Stay compliant — track insurance certificates and indemnity agreements (this side is largely deferred past the July pilot — see §2 of the charter).
  4. Cara — an AI assistant that can answer questions, generate documents, and help with estimating, all aware of what page/bid/project you're currently looking at.

Why this matters for QA: Cara is a system of record for money and legal/contractual commitments. The highest-value bugs are ones where numbers are wrong, data is lost, the wrong person can see confidential money data, or an immutable record got mutated (see §5). Cosmetic issues matter far less right now (see the lockdown rule in doc 04).

2. Who uses it — roles and what they can see

Cara has internal roles (Pinley employees, who log in) and an external portal (subcontractors/brokers who upload documents without an account). Internally there are ~14 roles grouped into 7 categories. You don't need to memorize all 14 — think in categories and remember the visibility rules.

Category Roles in it What they do
Executive Owner, Executive See everything, including profit/margin. Owner is the only role that can manage other roles' permissions.
Admin Administration (+ Admin Assistant) System config, users, settings.
Finance Financial Controller Billing, budgets, PO approvals, profitability.
PM (Project Management) Senior PM, Project Manager, Assistant PM Run awarded projects — submittals, RFIs, daily logs, change orders, budgets.
Estimating Chief Estimator, Estimator, Assistant Estimator Bids, estimates, takeoffs, proposals, vendor pricing.
Compliance Compliance Officer Insurance / COI tracking.
Field Field User, Superintendent On-site: daily logs, punch lists, photos. Superintendent is a newer role that inherits Field User's access plus a bit more (e.g. can reopen a completed daily log).
External Broker / Subcontractor No login. Access via a secure, token-based upload link only.

The visibility rules the product intends (from the client-approved prototype)

  • PMs never see profit data. A PM sees budget amounts but not profit margins, markups, or net profit. Those are for Senior Estimator, Executive, Owner (and Finance for some).
  • Estimators own preconstruction, not execution. Estimators live in bids/estimates/takeoffs/proposals. Projects, RFIs, submittals are PM territory.
  • Field crew is scoped to daily logs. The Field role has full daily-log access, read-only projects, and little else.
  • Compliance owns insurance. PMs can view insurance status but not manage it.
  • Finance owns AP/AR (accounts payable/receivable), PO approvals, billing.
  • Owner is the only role that can change the permission matrix.

⚠️ CRITICAL QA scope note — read this twice

The bullet points above describe the intended end-state. The July build does NOT yet enforce field-level financial masking. Two big pieces are deliberately deferred to September:

  • Field masking (hiding specific money fields like profit/margin from roles that shouldn't see them) — not implemented for July. So if you log in as a PM and can see a profit margin or markup, that is NOT a July bug — the masking layer simply isn't built yet.
  • The full 13-role permission matrix + an admin UI to edit it — deferred to September. July ships a fixed, hardcoded set of permissions.

What IS enforced in July and worth testing: - Module-level access — whether a role can reach a whole area at all (e.g. can a Field User open the Bids section? can an Estimator open a Project's RFI tab?). If a role can open a module it clearly shouldn't, or is blocked from one it should have, that's worth a ticket. - Action gating — whether Add/Edit/Delete buttons appear for roles that shouldn't have them.

When unsure whether a visibility difference is "a bug" or "the September masking that isn't built yet," ask me (Claude Code) — I can check whether that field/permission is in the current build. See doc 03.

3. The core end-to-end workflow

This is the spine of the product. Follow it once mentally; then the modules in doc 02 will make sense as stages of one story.

        PRECONSTRUCTION (Estimating owns)                     PROJECT EXECUTION (PM owns)
 ┌───────────────────────────────────────────┐   AWARD   ┌──────────────────────────────────────┐
 │ Bid Invite → Bid → Takeoff → Estimate →    │  ───────► │ Project → Daily Logs / RFIs /          │
 │ Vendor Outreach (quotes) → Proposal        │           │ Submittals / Change Orders / Billing   │
 └───────────────────────────────────────────┘           └──────────────────────────────────────┘
                        Cara AI assists throughout · Documents live in SharePoint (pilot) / Blob storage

Preconstruction (winning the work): 1. Bid Invite — a GC invites Pinley to bid on a project (often synced in from BuildingConnected or Procore). Pinley accepts or declines. 2. Bid — an accepted invite becomes a bid record. It has a status that moves forward through a pipeline (New → Qualifying → Estimating → … → Awarded / Lost / No-Bid / Withdrawn). This is a forward-only workflow — you can't move a bid backwards. 3. Takeoff — measuring quantities off the drawings (how many feet of duct, how many units, etc.). Cara has AI-assisted takeoff, plus Excel/CSV import. 4. Estimate — the priced-out cost of the work, built on a spreadsheet-like "estimate sheet" (sections, line items, vendor quote columns, markups, tax, overhead). Estimates use revisions (see §5). 5. Vendor Outreach — inviting vendors/subs to quote parts of the scope; logging their quotes. 6. Proposal — the formal document sent to the GC/client, generated as a PDF from a frozen snapshot of the estimate.

Award = the handoff. When a bid is Awarded, it becomes a Project and (optionally) Cara helps generate an SOV. This "bid → project" handoff is a critical transition to test.

Project execution (running the work): 7. Daily Logs — the field crew records each work day: manpower (which trades, how many workers, hours), materials, delays, safety notes, photos, work performed. A day is a Draft until someone Completes it, which locks it. 8. RFIs — formal questions to the GC/architect when something on the drawings is unclear. They have a status lifecycle (Open → Submitted → Answered → Closed) and can be exported to PDF. 9. Submittals — material/equipment data sent to the architect for approval before ordering (e.g. "here's the exact pump we intend to install — approve it"). They carry a spec section and cost code, and have an approval decision (Approved / Approved as Noted / Revise & Resubmit / Rejected). 10. Change Orders — changes to the contract scope or price after award. Has attachments and a PDF export. 11. Billing / SOV — drives progress billing: each line has a scheduled value, % complete, work completed, retainage, and balance, moving through an 8-state billing cycle (billing requested → PM in progress → submitted to AR → … → payment received).

Cross-cutting: - Cara rides along the whole time as a floating assistant and a full-page Hub; it's page-aware (knows which bid/project you're on). - Documents during the pilot live in SharePoint (Pinley's existing system) and Cara links out to them ("Open in SharePoint"); longer term Cara becomes the source of truth in its own blob storage.

4. Domain glossary

Construction/insurance/Cara terms you'll hit constantly now have their own page: 07 — Glossary. Bookmark that instead of this section — it's the one place these definitions are kept up to date, and it gets new terms added as testing surfaces them.

5. Immutability rules you must respect and verify

Some records in Cara are append-only — once created they are never edited or deleted; a change means creating a new version. This is intentional and legally important (you must be able to prove what the requirements/price were at a point in time). These are prime QA targets: try to break them, and confirm they hold.

  1. COI Revisions are append-only. Updating insurance requirements must create a new COIRevision with a higher revision number — never mutate an existing one. (Compliance is mostly out of the July pilot, but the rule holds wherever it appears.)
  2. Estimate Revisions are append-only snapshots. A revision freezes the estimate's numbers (including tax/insurance/overhead percentages) at the time it was created. Viewing an old revision must show the old numbers, even if the live estimate changed afterward.
  3. Proposal Revisions are append-only. A proposal PDF is generated from a frozen snapshot taken when the revision was created — it must never re-read live estimate data. The only things allowed to change on an existing proposal revision are the "is this the active one?" flag and a one-time stamp of the generated file.

How to test these: create a revision, note the numbers, then change the underlying data, then re-open the old revision — the old numbers must be preserved. If an "old" snapshot reflects new data, that's a serious integrity bug (Urgent/High).

Related integrity behaviors worth probing: - Audit log — significant state changes (status changes, awards, uploads) are supposed to write an immutable audit entry. Worth spot-checking that actions you take show up in the activity/audit trail. - Forward-only bid status — you should not be able to move a bid backward in its pipeline. Try it; it should be rejected. - Completed daily logs lock — once a work day is Completed, its child data (manpower/materials/etc.) should become read-only until a permitted role Reopens it.

Where to go next

  • 02 — Module Test Charter — turn this workflow into a concrete, prioritized test plan, with July-vs-September scope marked.
  • 03 — How to Test — get access, and learn to ask me "how is X supposed to behave?" before filing.