Punch List Contractor Assignment

Overview

When you create a punch item, BlueClerk suggests contractors based on trade, phase history, and recent usage - but never auto-assigns. You stay in control, reviewing suggestions and choosing who to assign with one tap. Once assigned, the contractor receives a magic link via SMS to view and resolve the item without needing a BlueClerk account.

How Contractor Suggestions Work

AI-Powered Ranking

When you create a punch item, BlueClerk analyzes:

• Trade match - Contractors who work in the relevant trade (plumbing, electrical, drywall, etc.)
• Phase history - Contractors who worked on this phase before at this property
• Recent usage - Contractors you've assigned to recently across your subdivisions

Suggestions appear ranked by relevance, with the most likely match at the top.

No Auto-Assignment

BlueClerk never auto-assigns contractors:

• You review suggestions before making a choice
• Tap to assign the contractor you want
• Manual override - assign anyone on your roster, not just suggestions
• Skip assignment - leave unassigned if you're not ready

Assigning a Contractor

From Punch Item Creation

1. Create a punch item with description and trade
2. See contractor suggestions ranked by AI
3. Review the list - trade match, phase history, recent work
4. Tap a contractor to assign them
5. Or skip and assign later

From Existing Punch Item

1. Open any punch item from the Punch List tab
2. Click "Assign Contractor"
3. See suggestions or pick from your full roster
4. Tap to assign

What Happens After Assignment

Automatic SMS Notification

When you assign a contractor:

• SMS is sent immediately to the contractor's phone
• Magic link included - tappable URL to view the punch item
• No login required - contractor can view and resolve without a BlueClerk account

Magic Link Access

When the contractor taps the magic link:

1. Punch item detail opens showing description, trade, property address, and photos
2. Contractor can mark "Resolved" with one tap
3. You're notified when they resolve it
4. Status updates in your punch list automatically

Server-Side Honeypot Validation

BlueClerk now includes server-side honeypot validation to block bot submissions. When contractors receive the magic link and open the punch item resolution page:

• Hidden honeypot field is positioned off-screen (left: -9999px)
• Real humans never see it - they fill out the visible form normally
• Bots auto-fill all fields including the honeypot
• Server returns fake success when honeypot is populated, preventing spam

This stops bots from submitting fake resolutions via the magic link endpoint. The client-side honeypot (already present in signup-client.tsx) now has matching server-side validation in the tRPC endpoint.

Reassigning a Contractor

If you need to change who's assigned:

1. Open the punch item
2. Click "Reassign"
3. Pick a new contractor from the list
4. New SMS is sent to the new contractor
5. Previous contractor's magic link is invalidated

Viewing Assigned Work

For Builders

• See assigned contractor on each punch item card
• Filter by contractor in the Punch List table view
• Track resolution status - Open, In Progress, Resolved

For Contractors

• Tap magic link in SMS to view punch item
• See property address and description
• Mark resolved when work is complete
• No app download required - works in any browser

Tips

• Assign early - Give contractors visibility as soon as punch items are created
• Use trade filtering - The AI prioritizes contractors who match the trade
• Check phase history - Contractors who worked on this phase before are ranked higher
• Review before sending - You can assign multiple items to one contractor, then they get one SMS with all items

Questions

Q: Can I assign multiple punch items to the same contractor at once?
A: Yes - assign multiple items, and the contractor receives one SMS with links to all items.

Q: What if the contractor doesn't have a phone number?
A: You can still assign them, but they won't receive the magic link SMS. You'll need to communicate the assignment another way.

Q: Can I assign a punch item to someone not on my roster?
A: No - only contractors you've added to your roster appear in the assignment list. Add them to your roster first, then assign.

Q: How long is the magic link valid?
A: Magic links don't expire - they work until the punch item is resolved or you reassign it to someone else.

Q: What stops bots from submitting fake resolutions via the magic link?
A: Server-side honeypot validation blocks bot submissions - a hidden field is checked on every resolution request, and bots that auto-fill it receive fake success responses while their submissions are ignored.