Punch List Manager for Construction Closeout
Complete system for managing construction punch lists from creation through final acceptance.
Business Case
Problem: Punch list management is inefficient:
- Paper lists get lost or outdated
- Difficult to track completion status
- Photos disconnected from items
- Back-charges delayed due to poor documentation
- Multiple walks create duplicate items
Solution: Digital punch list system that:
- Creates items with photos and location markup
- Assigns to responsible parties with deadlines
- Tracks completion with before/after photos
- Generates back-charge documentation
- Provides real-time completion dashboards
ROI: 50% faster closeout, 80% reduction in disputed back-charges
Punch List Workflow
┌──────────────────────────────────────────────────────────────────────┐
│ PUNCH LIST WORKFLOW │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ CREATION ASSIGNMENT COMPLETION │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Walk │────────►│ Assign │────────►│ Correct │ │
│ │ Site │ │ Items │ │ Items │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Log │ │ Notify │ │ Submit │ │
│ │ Items │ │ Parties │ │ Photo │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Photo │ │ Set │ │ Mark │ │
│ │ + Tag │ │ Deadline│ │ Complete│ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │
│ ▼ │
│ VERIFICATION CLOSEOUT ┌─────────┐ │
│ ┌─────────┐ ┌─────────┐ │ Verify │ │
│ │ Re-walk │◄────────│ Accept │◄───────│ Work │ │
│ │ Site │ │ Items │ └─────────┘ │
│ └─────────┘ └─────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ │
│ │ New │ │ Final │ │
│ │ Items? │────NO──►│ Accept │ │
│ └────┬────┘ └─────────┘ │
│ │YES │
│ └──────────────► Back to CREATION │
│ │
└──────────────────────────────────────────────────────────────────────┘Data Structure
from dataclasses import dataclass, field
from datetime import datetime, date
from enum import Enum
from typing import List, Optional
import uuid
class PunchItemStatus(Enum):
OPEN = "Open"
ASSIGNED = "Assigned"
IN_PROGRESS = "In Progress"
READY_FOR_VERIFICATION = "Ready for Verification"
VERIFIED = "Verified"
REJECTED = "Rejected"
ACCEPTED = "Accepted"
class PunchItemPriority(Enum):
CRITICAL = "Critical" # Life safety / code compliance
HIGH = "High" # Affects occupancy
MEDIUM = "Medium" # Standard punch
LOW = "Low" # Minor / cosmetic
OBSERVATION = "Observation"
class TradeCategory(Enum):
GENERAL = "General Contractor"
ELECTRICAL = "Electrical"
PLUMBING = "Plumbing"
HVAC = "HVAC"
FIRE_PROTECTION = "Fire Protection"
DRYWALL = "Drywall/Painting"
FLOORING = "Flooring"
MILLWORK = "Millwork/Casework"
GLAZING = "Glazing"
ROOFING = "Roofing"
SITEWORK = "Sitework"
LANDSCAPING = "Landscaping"
CONTROLS = "Controls/BMS"
OTHER = "Other"
@dataclass
class PunchItem:
item_id: str
punch_list_id: str
description: str
location: str
trade: TradeCategory
priority: PunchItemPriority
# Location details
building: str = ""
floor: str = ""
room: str = ""
# Assignment
assigned_to: str = ""
assigned_date: date = None
due_date: date = None
# Documentation
photo_before: str = ""
photo_after: str = ""
drawing_markup: str = ""
spec_reference: str = ""
# Status tracking
status: PunchItemStatus = PunchItemStatus.OPEN
created_by: str = ""
created_date: date = field(default_factory=date.today)
# Completion
completed_by: str = ""
completed_date: date = None
completion_notes: str = ""
# Verification
verified_by: str = ""
verified_date: date = None
verification_notes: str = ""
# Back-charge
back_charge: bool = False
back_charge_amount: float = 0.0
back_charge_ref: str = ""
# History
history: List[dict] = field(default_factory=list)
@dataclass
class PunchList:
list_id: str
project_id: str
name: str
walk_date: date
walk_attendees: List[str]
items: List[PunchItem] = field(default_factory=list)
status: str = "Active" # Active, Complete
created_by: str = ""
created_date: date = field(default_factory=date.today)
area: str = "" # Building/floor/zone covered
list_type: str = "Punch" # Punch, Pre-Punch, FinalPython Implementation
import pandas as pd
from datetime import datetime, date, timedelta
from typing import List, Dict, Optional
from collections import defaultdict
class PunchListManager:
"""Construction punch list management system"""
def __init__(self, project_id: str, storage_path: str = None):
self.project_id = project_id
self.storage_path = storage_path or f"punch_{project_id}"
self.punch_lists: Dict[str, PunchList] = {}
self.items: Dict[str, PunchItem] = {}
def create_punch_list(
self,
name: str,
walk_date: date,
attendees: List[str],
area: str = "",
list_type: str = "Punch",
created_by: str = ""
) -> PunchList:
"""Create new punch list from walk"""
list_id = f"PL-{datetime.now().strftime('%Y%m%d%H%M%S')}"
punch_list = PunchList(
list_id=list_id,
project_id=self.project_id,
name=name,
walk_date=walk_date,
walk_attendees=attendees,
area=area,
list_type=list_type,
created_by=created_by
)
self.punch_lists[list_id] = punch_list
return punch_list
def add_item(
self,
punch_list_id: str,
description: str,
location: str,
trade: TradeCategory,
priority: PunchItemPriority = PunchItemPriority.MEDIUM,
building: str = "",
floor: str = "",
room: str = "",
photo_before: str = "",
drawing_markup: str = "",
spec_reference: str = "",
created_by: str = ""
) -> PunchItem:
"""Add item to punch list"""
if punch_list_id not in self.punch_lists:
raise ValueError(f"Punch list {punch_list_id} not found")
# Generate item ID
punch_list = self.punch_lists[punch_list_id]
item_num = len(punch_list.items) + 1
item_id = f"{punch_list_id}-{item_num:04d}"
item = PunchItem(
item_id=item_id,
punch_list_id=punch_list_id,
description=description,
location=location,
trade=trade,
priority=priority,
building=building,
floor=floor,
room=room,
photo_before=photo_before,
drawing_markup=drawing_markup,
spec_reference=spec_reference,
created_by=created_by
)
# Add history entry
item.history.append({
'date': datetime.now(),
'action': 'Created',
'by': created_by,
'notes': ''
})
self.items[item_id] = item
punch_list.items.append(item)
return item
def assign_item(
self,
item_id: str,
assigned_to: str,
due_date: date = None,
assigned_by: str = ""
) -> PunchItem:
"""Assign item to responsible party"""
item = self.items.get(item_id)
if not item:
raise ValueError(f"Item {item_id} not found")
if due_date is None:
# Default due dates by priority
days = {
PunchItemPriority.CRITICAL: 1,
PunchItemPriority.HIGH: 3,
PunchItemPriority.MEDIUM: 7,
PunchItemPriority.LOW: 14,
PunchItemPriority.OBSERVATION: 30
}
due_date = date.today() + timedelta(days=days.get(item.priority, 7))
item.assigned_to = assigned_to
item.assigned_date = date.today()
item.due_date = due_date
item.status = PunchItemStatus.ASSIGNED
item.history.append({
'date': datetime.now(),
'action': 'Assigned',
'by': assigned_by,
'notes': f'Assigned to {assigned_to}, due {due_date}'
})
# Trigger notification
self._notify_assignment(item)
return item
def mark_complete(
self,
item_id: str,
completed_by: str,
photo_after: str = "",
completion_notes: str = ""
) -> PunchItem:
"""Mark item as completed by trade"""
item = self.items.get(item_id)
if not item:
raise ValueError(f"Item {item_id} not found")
item.completed_by = completed_by
item.completed_date = date.today()
item.photo_after = photo_after
item.completion_notes = completion_notes
item.status = PunchItemStatus.READY_FOR_VERIFICATION
item.history.append({
'date': datetime.now(),
'action': 'Completed',
'by': completed_by,
'notes': completion_notes
})
return item
def verify_item(
self,
item_id: str,
verified_by: str,
accepted: bool,
notes: str = ""
) -> PunchItem:
"""Verify completed item"""
item = self.items.get(item_id)
if not item:
raise ValueError(f"Item {item_id} not found")
item.verified_by = verified_by
item.verified_date = date.today()
item.verification_notes = notes
if accepted:
item.status = PunchItemStatus.ACCEPTED
action = 'Accepted'
else:
item.status = PunchItemStatus.REJECTED
action = 'Rejected'
# Re-assign for rework
item.assigned_date = date.today()
item.due_date = date.today() + timedelta(days=3)
item.history.append({
'date': datetime.now(),
'action': action,
'by': verified_by,
'notes': notes
})
return item
def add_back_charge(
self,
item_id: str,
amount: float,
reference: str = ""
) -> PunchItem:
"""Add back-charge to item"""
item = self.items.get(item_id)
if not item:
raise ValueError(f"Item {item_id} not found")
item.back_charge = True
item.back_charge_amount = amount
item.back_charge_ref = reference
item.history.append({
'date': datetime.now(),
'action': 'Back Charge',
'by': '',
'notes': f'Amount: ${amount:.2f}, Ref: {reference}'
})
return item
def get_items_by_trade(self, trade: TradeCategory) -> List[PunchItem]:
"""Get all items for a specific trade"""
return [i for i in self.items.values() if i.trade == trade]
def get_items_by_status(self, status: PunchItemStatus) -> List[PunchItem]:
"""Get items by status"""
return [i for i in self.items.values() if i.status == status]
def get_overdue_items(self) -> List[PunchItem]:
"""Get overdue items"""
today = date.today()
return [
i for i in self.items.values()
if i.status in [PunchItemStatus.OPEN, PunchItemStatus.ASSIGNED, PunchItemStatus.IN_PROGRESS]
and i.due_date and i.due_date < today
]
def get_statistics(self) -> dict:
"""Get punch list statistics"""
all_items = list(self.items.values())
if not all_items:
return {'total': 0}
by_status = defaultdict(int)
by_trade = defaultdict(lambda: {'total': 0, 'open': 0})
by_priority = defaultdict(int)
for item in all_items:
by_status[item.status.value] += 1
by_trade[item.trade.value]['total'] += 1
if item.status not in [PunchItemStatus.ACCEPTED, PunchItemStatus.VERIFIED]:
by_trade[item.trade.value]['open'] += 1
by_priority[item.priority.value] += 1
# Calculate completion rate
accepted = len([i for i in all_items if i.status == PunchItemStatus.ACCEPTED])
completion_rate = accepted / len(all_items) * 100 if all_items else 0
# Back charges
back_charge_items = [i for i in all_items if i.back_charge]
total_back_charges = sum(i.back_charge_amount for i in back_charge_items)
return {
'total': len(all_items),
'by_status': dict(by_status),
'by_trade': dict(by_trade),
'by_priority': dict(by_priority),
'completion_rate': round(completion_rate, 1),
'overdue': len(self.get_overdue_items()),
'back_charge_count': len(back_charge_items),
'back_charge_total': total_back_charges
}
def generate_trade_report(self, trade: TradeCategory) -> str:
"""Generate report for specific trade"""
items = self.get_items_by_trade(trade)
report = f"""
╔══════════════════════════════════════════════════════════════╗
║ PUNCH LIST - {trade.value.upper():<30} ║
║ Project: {self.project_id:<40} ║
║ Date: {date.today().strftime('%d.%m.%Y'):<43} ║
╠══════════════════════════════════════════════════════════════╣
Total Items: {len(items)}
Open: {len([i for i in items if i.status not in [PunchItemStatus.ACCEPTED]])}
Due Today: {len([i for i in items if i.due_date == date.today()])}
Overdue: {len([i for i in items if i.due_date and i.due_date < date.today() and i.status not in [PunchItemStatus.ACCEPTED]])}
ITEMS REQUIRING ACTION
───────────────────────────────────────────────────────────────
"""
for item in items:
if item.status not in [PunchItemStatus.ACCEPTED]:
overdue_flag = "🔴" if item.due_date and item.due_date < date.today() else ""
report += f"""
{overdue_flag} [{item.item_id}] {item.priority.value}
Location: {item.location}
Description: {item.description}
Status: {item.status.value}
Due: {item.due_date}
"""
report += """
╚══════════════════════════════════════════════════════════════╝
"""
return report
def generate_summary_dashboard(self) -> str:
"""Generate overall punch list dashboard"""
stats = self.get_statistics()
report = f"""
╔══════════════════════════════════════════════════════════════════╗
║ PUNCH LIST DASHBOARD ║
║ Project: {self.project_id:<40} ║
║ Date: {date.today().strftime('%d.%m.%Y'):<43} ║
╠══════════════════════════════════════════════════════════════════╣
📊 OVERALL STATUS
───────────────────────────────────────────────────────────────────
Total Items: {stats['total']}
Completion Rate: {stats['completion_rate']}%
Overdue Items: {stats['overdue']}
📈 BY STATUS
───────────────────────────────────────────────────────────────────
"""
for status, count in stats['by_status'].items():
bar = "█" * int(count / max(stats['by_status'].values()) * 20) if stats['by_status'] else ""
report += f" {status:<25} {count:>5} {bar}\n"
report += """
🔧 BY TRADE (Open Items)
───────────────────────────────────────────────────────────────────
"""
for trade, data in sorted(stats['by_trade'].items(), key=lambda x: x[1]['open'], reverse=True):
if data['open'] > 0:
report += f" {trade:<25} {data['open']:>5} open / {data['total']} total\n"
report += f"""
💰 BACK CHARGES
───────────────────────────────────────────────────────────────────
Items with Back Charges: {stats['back_charge_count']}
Total Back Charges: ${stats['back_charge_total']:,.2f}
╚══════════════════════════════════════════════════════════════════╝
"""
return report
def _notify_assignment(self, item: PunchItem):
"""Send notification for assigned item"""
print(f"📋 Punch item assigned: {item.item_id}")
print(f" To: {item.assigned_to}")
print(f" Due: {item.due_date}")
print(f" Location: {item.location}")
def export_to_excel(self, output_path: str) -> str:
"""Export punch list to Excel"""
records = []
for item in self.items.values():
records.append({
'Item ID': item.item_id,
'Description': item.description,
'Location': item.location,
'Building': item.building,
'Floor': item.floor,
'Room': item.room,
'Trade': item.trade.value,
'Priority': item.priority.value,
'Status': item.status.value,
'Assigned To': item.assigned_to,
'Due Date': item.due_date,
'Completed By': item.completed_by,
'Completed Date': item.completed_date,
'Back Charge': 'Yes' if item.back_charge else 'No',
'Back Charge Amount': item.back_charge_amount if item.back_charge else '',
'Photo Before': item.photo_before,
'Photo After': item.photo_after
})
df = pd.DataFrame(records)
df.to_excel(output_path, index=False)
return output_path
# Usage Example
if __name__ == "__main__":
# Initialize manager
manager = PunchListManager(project_id="PROJECT-2026-001")
# Create punch list from walk
punch_list = manager.create_punch_list(
name="Floor 5 Pre-Final Walk",
walk_date=date.today(),
attendees=["PM", "Architect", "GC Super"],
area="Building A, Floor 5",
list_type="Pre-Final",
created_by="PM"
)
# Add items
item1 = manager.add_item(
punch_list_id=punch_list.list_id,
description="Touch up paint at door frame Room 501",
location="Room 501, door frame",
trade=TradeCategory.DRYWALL,
priority=PunchItemPriority.LOW,
building="A",
floor="5",
room="501",
created_by="PM"
)
item2 = manager.add_item(
punch_list_id=punch_list.list_id,
description="Missing cover plate on electrical outlet",
location="Room 502, east wall",
trade=TradeCategory.ELECTRICAL,
priority=PunchItemPriority.MEDIUM,
building="A",
floor="5",
room="502",
created_by="PM"
)
# Assign items
manager.assign_item(
item_id=item1.item_id,
assigned_to="ABC Painting",
assigned_by="GC Super"
)
manager.assign_item(
item_id=item2.item_id,
assigned_to="XYZ Electric",
due_date=date.today() + timedelta(days=2),
assigned_by="GC Super"
)
# Mark complete
manager.mark_complete(
item_id=item1.item_id,
completed_by="ABC Painting",
completion_notes="Paint touched up"
)
# Verify
manager.verify_item(
item_id=item1.item_id,
verified_by="PM",
accepted=True,
notes="Looks good"
)
# Generate reports
print(manager.generate_summary_dashboard())
print(manager.generate_trade_report(TradeCategory.ELECTRICAL))Telegram Bot Integration
name: Punch List Bot
commands:
/newitem:
steps:
- Ask: Photo of deficiency
- Ask: Location (Building/Floor/Room)
- Ask: Description
- Ask: Trade (show buttons)
- Ask: Priority (show buttons)
- Confirm and create item
/myitems:
- Show open items assigned to user
- Buttons: [Mark Complete] [View Details]
/complete:
- Select item from list
- Ask for completion photo
- Ask for notes
- Submit for verification
/dashboard:
- Show summary statistics
- Open items by trade
- Overdue items*"The last 10% of punch takes 50% of the time. Start early, stay organized."*