Defects

A defect in IssuesId is any tracked site issue — a quality problem, a variation request, or a backcharge claim. Every defect carries a full lifecycle with role-gated transitions, so the audit trail holds up in claims, disputes, and PC sign-off.

The lifecycle

Defects move through a fixed sequence of states:

1. 01Open — the default state when a defect is first captured. Not yet assigned to anyone.
2. 02Assigned — sent to a trade or sub-contractor.
3. 03Pending — work in progress, awaiting completion.
4. 04Fixed — the trade has marked the issue as resolved.
5. 05Trade completed — sub-contractor sign-off that the fix is genuine.
6. 06Ready to inspect — handed back for verification.
7. 07Closed — verified and signed off. Terminal state — closed defects can't be re-opened.

Two additional states sit outside the happy path:

• →Outstanding — used as an escalation or exception flag when a defect can't progress through the normal path (e.g. blocked by a design decision, missing material, dispute resolved against the assignee).
• →In dispute — set automatically by the system when an assignment is disputed. Users can't transition into this state manually; it's derived from underlying assignment activity.

Each transition is role-gated. A contractor can't close their own work, a supervisor can't be bypassed, and every state change is timestamped against the user who made it.

Capturing a defect

The capture flow is intentionally short — under 30 seconds for an experienced user.

• →Photo — one or more, taken in-app or imported from camera roll.
• →Location — drop a pin on the project drawing, or scan a QR code that pre-fills it.
• →Voice note — dictated description; transcribed automatically.
• →Category — what kind of defect this is (e.g. Plumbing, Tiling, Water Leak — Bathroom Membrane). Optional. See below.
• →Trade and priority — drives routing and SLA timing.
• →Cost category — defect, variation, or backcharge. This flag follows the record into reports.

Categories

The category field uses an organisation-wide taxonomy — a configurable list of defect types that's shared across every project in your org. New organisations are seeded with ~80 sensible defaults covering trades (carpentry, plumbing, electrical, …), failure types (chip / scratch / mark / dent, water leak — and a dozen sub-types of that), and admin entries (duplicate entry, not a builder's defect, waiting on image).

You can edit the taxonomy any time:

• →Add or rename categories to match your team's vocabulary.
• →Reorder them in the picker.
• →Deactivate categories that no longer apply (without destroying historical defects that used them).
• →Exclude per project — a category that's relevant on most jobs but not on a specific one can be turned off for that one project, keeping the picker tight for the team on site.

Category is optional on a defect — captures without one are still valid records. It's there to help filtering, reporting, and trade-routing, not to gate the capture flow.

Cost tracking

A defect carries two contractor links, and the distinction matters when it comes time to invoice:

• →The assignee (set per assignment) is the contractor doing the work. They get the notification, they update the assignment status, they sign off when complete.
• →The cost-to contractor is who gets billed for the work. It's set per-defect, separate from any assignment.

Most of the time these are the same. The split exists for the cases where they aren't — for example, when Trade A is doing the rework but Trade B caused the issue and is being backcharged, or when an internal team handles the fix but an external party is billed. The cost-to contractor field captures that intent in a structured way, so reports and exports reflect who actually pays.

The defect also carries an optional cost value and a cost code (drawn from the project's configured cost code list). Together with the cost category (defect / variation / backcharge) and the cost-to contractor, that's a complete record line for the accounts team.

Comments & notes

Every defect has a conversation thread — internal and shared comments attached to the record. Each note has:

• →An author, recorded at the user level.
• →A visibility scope — one of:

- internal — only your own team sees it. - shared_trade — visible to assigned trades. - shared_tenant — visible to the tenant scoped to this defect's unit. - shared_client — visible to client-role users on the project. - shared_all — visible to everyone who can see the defect.

• →An optional assignment link — notes can be tied to a specific assignment thread when context matters (e.g. back-and-forth on a particular trade's rework).
• →Edit tracking — if a note is edited after posting, the edit timestamp is recorded and a revision count is incremented. Recipients see "edited" markers; the platform doesn't pretend the edit didn't happen.
• →Soft delete — a deleted note leaves a tombstone, not a hole. The thread shows that something was removed and when, without exposing the content.

This is the surface that replaces the old fixed "internal notes / client notes / builder response" columns. The conversation model means a defect's discussion can be longer than three messages and audited just as cleanly.

Time-in-progress tracking

The first time a defect transitions out of open — when work actually starts — the platform stamps an in-progress timestamp on the record. Once set, it's never cleared and never updated. That gives reports and dashboards a clean "time-in-progress" measure that's independent of when the defect was first captured.

The defect list endpoints support inProgressFrom and inProgressTo query parameters to filter on this date range — useful for SLA reports, aging analyses, and "what got picked up this week" queries.

Annotations

Photos and drawings support overlay markup:

• →Pin — drop a numbered pin with an optional caption.
• →Circle / arrow / text — call out the exact problem area.
• →Voice caption per pin — speak instead of typing.

Pin colour reflects status, so a foreman scanning a plan sees open issues at a glance.

Disputes and history

If a trade disputes a defect (e.g. claims it's design intent, not a fault), they raise a dispute. The defect pauses in its current state until a supervisor adjudicates. Both the dispute reason and the resolution are recorded.

Every defect has a full history view: who did what, when, with what evidence. This view is the source of truth in claims and contract disputes.

Bulk actions

For projects with hundreds of defects:

• →Bulk assign by location, trade, or filter set.
• →Bulk export to CSV or PDF.
• →Bulk close after a verified inspection sweep.

What to read next

• →Inspections — failed checklist items become linked defects automatically.
• →Work orders — group related defects into a single trade engagement.