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, archive items to clean up your active list while keeping them recoverable, 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.)
   • Severity: Critical, Major, or Minor
   • Location: Select room from floor plan or enter custom location
   • Notes: Additional context or special instructions
5. Add photos (optional but recommended)
6. Pin to floor plan (optional) - Click a location on the uploaded floor plan image
7. Assign contractor (optional) - Choose from AI-suggested contractors or your roster
8. Click "Create"

Severity Levels

• Critical - Safety issues, code violations, or major defects that prevent closeout
• Major - Significant issues that affect functionality or appearance
• Minor - Small cosmetic issues or touch-ups

Archiving Punch Items

What Archive Does

Archiving removes a punch item from your active list while keeping it fully recoverable in the database. Use archive for:

• Items that are no longer relevant (scope changed, homeowner accepted "as-is")
• Duplicate entries you want to hide but not permanently delete
• Items you want to temporarily remove from reports or counts

Archive is NOT delete - archived items can be restored at any time.

How to Archive

From the punch list edit dialog:

1. Open a punch item by clicking its row in any punch list table or the property Punch List tab
2. Click "Archive" button in the dialog footer (left side, red text)
3. Confirm when prompted
4. Item disappears from active lists immediately
5. Property and portfolio counts update - archived items don't count toward open/pending totals

Restoring Archived Items

To bring back an archived punch item:

1. Navigate to Builder > Punch List (table view)
2. Filter by "Archived" status using the status dropdown
3. Click the archived item row to open its edit dialog
4. Click "Restore" button in the dialog footer
5. Item returns to active list with its original status

Tracking Resolution

Punch Item Statuses

• Open - Not started yet
• In Progress - Contractor is working on it
• Pending Verification - Work claimed complete, awaiting your inspection
• Completed - Verified and signed off
• Archived - Removed from active list (recoverable)

Contractor Updates

When a contractor is assigned via magic link:

1. They view the item without logging in
2. They can upload photos of their work
3. They mark it "Complete" which sets status to Pending Verification
4. You receive a notification to inspect and verify

Builder Verification

1. Review contractor's work on-site or via uploaded photos
2. If acceptable: Change status to Completed
3. If not acceptable: Add notes, change back to In Progress, and notify contractor

AI Knowledge Base

What Gets Embedded

Every punch item you create is embedded into BlueClerk's RAG (Retrieval-Augmented Generation) knowledge base:

• Description of the issue
• Resolution notes after completion
• Photos of before/after
• Trade and severity metadata

How AI Uses It

When you create new punch items or use Smart Estimator:

• AI suggests similar past issues you've resolved
• Shows how you fixed similar problems before
• Helps contractors understand your quality standards
• Improves estimates based on actual punch list history

Tips

• Add photos - Visual documentation protects you and helps contractors understand exactly what needs fixing
• Use floor plan pins - Makes it easy to find issues during walkthrough
• Assign severity accurately - Critical items should truly block closeout
• Archive instead of delete - Keep your data recoverable while cleaning up active lists
• Write clear descriptions - "Touch up paint in master bedroom doorway" beats "paint issue"
• Update status promptly - Keeps contractors and homeowners informed

Questions

Q: What's the difference between archive and delete?
A: Archive hides the item from your active list but keeps it fully recoverable in the database. It won't count toward your open/pending totals or appear in reports, but you can restore it anytime. Delete would permanently remove it (though we don't currently offer hard delete for punch items).

Q: Can homeowners see archived punch items?
A: No - archived items are hidden from all views and reports. Only you can see them by filtering for "Archived" status in the punch list table.

Q: Will archiving affect my property counts?
A: Yes - archived items are excluded from open/pending/critical counts on the Punch Overview page and property detail cards. Your counts will reflect only active punch items.

Q: What happens if I archive an item that was assigned to a contractor?
A: The contractor's magic link will still work, but the item will show as archived. They can still view it but cannot update its status. If you restore the item later, the contractor assignment remains intact.

Q: Can I filter reports to exclude archived items?
A: Yes - PDF exports and table views automatically exclude archived items by default. You must explicitly filter for "Archived" status to see them.