Punch List System

Overview

The punch list system helps builders track defects and incomplete work during construction and at final walkthroughs. Create punch items with photos and floor plan pins, assign them to contractors, track resolution progress, and build a permanent RAG-embedded knowledge base of common issues and how they were resolved.

Creating Punch Items

Adding a Punch Item

1. Open a property detail page
2. Go to the "Punch List" tab
3. Click "New Punch Item"
4. Fill in details:
   • Description: What needs to be fixed (required)
   • Trade: Select trade responsible (plumbing, electrical, drywall, etc.)
   • Room: Where the issue is located (optional)
   • Location: Specific location within room (optional)
   • Severity: CRITICAL, STANDARD, or COSMETIC (defaults to STANDARD)
   • Due Date: When it should be completed (optional)
   • Phase: Link to construction phase (optional)
   • Photos: Upload images of the defect
   • Floor Plan Pin: Click on floor plan to mark exact location

Automatic Item Numbering

Each punch item gets a unique number (e.g., PI-001, PI-002) automatically when created. Item numbers are atomic and never duplicate, even with multiple users creating items simultaneously.

Contractor Assignment

Punch items can be assigned to contractors in two ways:

• Manual: Select a contractor when creating the item
• Automatic: If linked to a construction phase with an assigned contractor, the contractor is auto-assigned

Punch Item Workflow

Contractor Receives Job Request

When a punch item is created with a contractor assigned:

1. Job request is sent to the contractor automatically
2. Contractor accepts the work request
3. Contractor schedules the repair
4. Contractor completes the work and uploads photos
5. System creates RAG embedding of the completed work

Builder Verification

After contractor marks work complete:

1. Builder receives notification that work is ready for review
2. Builder inspects the completed repair
3. Builder can:
   • Verify: Accept the work as complete
   • Reject: Send back for additional work with notes
   • Resolve: Mark fully resolved

RAG Embeddings

The system automatically creates AI embeddings at two stages:

• Defect embedding: Created when punch item is first documented (captures issue description, trade, severity, room, location, photos, AI analysis)
• Resolution embedding: Created when builder verifies completion (captures resolution notes, time to resolve, final status, contractor performance)

These embeddings power future AI suggestions and pattern recognition across all your properties.

Using Punch Templates

What Are Punch Templates?

Reusable checklists for common inspection scenarios - final walkthrough, rough-in inspection, drywall check, etc.

Creating a Template

1. Go to Builder > Punch Templates
2. Click "New Template"
3. Name your template (e.g., "Final Walkthrough Checklist")
4. Add template items:
   • Description of what to check
   • Trade responsible
   • Default severity
5. Save template

Applying a Template

1. Open a property punch list tab
2. Click "Apply Template"
3. Select template from dropdown
4. Review generated items - one punch item created for each template item
5. Edit or delete any items that don't apply
6. Assign contractors as needed

Punch List Reports

Generating Summary Reports

1. Go to property punch list tab
2. Click "Generate Summary"
3. PDF report includes:
   • Total items by severity
   • Items by trade
   • Items by contractor
   • Open vs. resolved counts
   • Average time to resolution
   • Photos of unresolved items

Contractor Performance Tracking

View metrics across all your properties:

• Average resolution time by contractor
• Rejection rate (items sent back for rework)
• Most common defect types by trade
• Seasonal patterns in punch item creation

Homeowner Walk Items

Converting Homeowner Feedback

When homeowners report issues during their walkthrough:

1. Create punch item with isHomeownerItem: true flag
2. Item is tagged as homeowner-reported in the system
3. RAG embeddings include "Source: homeowner walk item"
4. Track separately for warranty vs. builder QC issues

Tips

• Use floor plan pins to mark exact locations - helps contractors find issues quickly
• Take detailed photos of defects before and after repair
• Link to construction phases to track which stage issues occur most often
• Set due dates based on closing timeline or warranty deadlines
• Use severity levels to prioritize critical issues (safety, code violations) over cosmetic ones
• Apply templates consistently across similar properties for better comparison data

Questions

Q: Can I create punch items before assigning a contractor? A: Yes. Leave the contractor field blank and assign later, or link to a construction phase and the contractor will auto-assign when you add one to that phase.

Q: What happens if a contractor rejects a punch item? A: Contractors can't reject punch items - only accept and complete them. Builders can reject contractor-submitted completions and send them back for rework.

Q: How are punch item numbers generated? A: Automatically and atomically using a database counter on the property. Each property has its own sequence starting at 1.

Q: Can I delete a punch item? A: Yes, but it's better to mark items as "Skipped" or "Not Applicable" to preserve the record and prevent gaps in item numbering.

Q: Do punch items sync to RAG embeddings immediately? A: Embedding happens asynchronously (fire-and-forget) so it doesn't slow down punch item creation. Defect embeddings are created immediately; resolution embeddings are created when builder verifies completion.

Q: What's the difference between "Complete" and "Resolved"? A: "Complete" means the contractor finished the work. "Resolved" means the builder verified and accepted it. Items can be complete but not yet resolved if waiting for builder inspection.