# Punch List

> Track punch list items from identification through completion. Handles item creation, status updates, photo documentation, back-charge tracking, and report generation. Groups by area or trade for efficient closeout. Integrates with project dashboard (completion % by area and trade). Triggers: "punch list", "punch item", "punchlist", "add punch", "punch status", "generate punch list", "closeout", "deficiency", "back charge", "back-charge".

- Skill: `mgoodman60/punch-list` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add mgoodman60/punch-list`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mgoodman60/punch-list/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: mgoodman60 (https://skillmd.com/u/mgoodman60)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mgoodman60/punch-list

---


# Punch List Skill

## Overview
Comprehensive punch list management system for construction projects. Tracks identification and resolution of deficiencies from initial walk-through through final closeout. Supports photo documentation, back-charge management, and professional reporting for inspections and regulatory compliance.

## Punch Item Schema

### Core Fields
- **id** (string): Unique identifier, format "PUNCH-{NNN}" (e.g., "PUNCH-001", "PUNCH-042")
  - Auto-generated on creation, incremental within project
  - Never reused, immutable
  - Enables clear reference in conversations and reports

### Location Fields (One or more required)
- **room_number** (string): Room or space identifier (e.g., "Room 107", "306B", "ICU-2")
  - Used for healthcare: patient rooms, operating rooms, medication dispensary
  - Standard for office/commercial: office numbers, conference rooms
- **building_area** (string): Larger zone reference (e.g., "East Wing", "3rd Floor", "North Corridor")
  - Supports multi-floor, multi-wing projects
  - Hierarchical: "Building A > East Wing > 3rd Floor"
- **grid_reference** (string): Coordinate system, optional (e.g., "Grid C3", "Section 4B")
  - Used in large-scale or modular projects
- **floor_level** (integer): Floor number or level (e.g., 3, -1 for basement)
  - Supports vertical organization; assists in access planning

### Identification & Documentation
- **description** (string, required): Clear, specific deficiency description
  - Example: "Drywall mud pops in northeast corner, joint at ceiling"
  - Example: "Paint scuff on south wall, 5 ft from floor"
  - Example: "Nurse call button missing in Room 214"
  - Should include location detail within space and visible severity
- **trade** (string, required): Responsible trade/discipline
  - Examples: "Drywall", "Painting", "Electrical", "Plumbing", "HVAC", "Doors & Hardware", "Flooring", "Medical Equipment", "IT/Communications"
  - Used to group items and assign to responsible subs
- **responsible_sub** (string, required): Sub contractor name or entity
  - Resolved against {workspace}/subs/ directory
  - Example: "ABC Drywall Inc.", "Ready Paint Services", "Smith Plumbing"
- **date_identified** (date): Date item was discovered
  - Auto-populated on creation (today's date)
  - Supports historical tracking and aging analysis
- **identified_by** (string): Name of person who identified the item
  - Usually superintendent or foreman
  - Accountability and follow-up contact

### Status & Workflow
- **status** (enum): Current state of item
  - **open**: Newly identified, awaiting assignment
  - **in_progress**: Sub notified and work initiated
  - **completed**: Work finished, may be pending inspection
  - **back_charge**: Assigned back-charge (sub failed to correct)
  - **disputed**: Item contested by sub or stakeholder; requires resolution meeting
- **date_completed** (date, optional): When work was finished
  - Populated on transition to "completed"
  - Blank until completion
- **completed_by** (string, optional): Name of person who verified completion
  - Usually superintendent or inspector
  - Supports audit trail

### Priority Classification
- **priority** (enum): Urgency and impact level
  - **A (Critical)**: Safety violation or code non-compliance
    - Must be corrected before occupancy
    - Examples: Missing handrails, electrical safety hazards, ADA accessibility failures, infection control violations
    - Blocks final sign-off
  - **B (Functional)**: Affects proper use or function
    - Should be corrected before final inspection
    - Examples: Non-functioning door, HVAC controls not working, plumbing leaks, paint color mismatch affecting space function
    - May delay closeout
  - **C (Cosmetic)**: Appearance only, no safety/function impact
    - Minor touch-ups acceptable during or after occupancy
    - Examples: Small paint scuff, minor drywall finish, cosmetic grout gaps
    - Does not block closeout if agreed with owner

### Photos & Documentation
- **photos** (array of objects): Visual documentation
  - Each photo object contains:
    - **filename** (string): File path or reference (e.g., "/data/photos/PUNCH-001-1.jpg")
    - **description** (string): What the photo shows (e.g., "Overview of mud pops in NE corner")
    - **date_taken** (date): When photo was captured
  - Supports multiple photos per item
  - Embedded in .docx reports (with file size limits)
  - Clarity: well-lit, straight-on, includes reference object for scale

### Back-Charge Tracking
- **back_charge_amount** (decimal, optional): Dollar amount to charge to sub
  - Only populated if status = "back_charge"
  - Example: 250.00 (for corrective work cost)
  - Supports billing and dispute resolution
- **back_charge_sub** (string, optional): Sub entity assigned back-charge
  - Populated when status = "back_charge"
  - May differ from responsible_sub if sub contracted work to another party
- **back_charge_reason** (string, optional): Why back-charge was issued
  - Example: "Sub failed to correct deficiency within agreed timeframe"
  - Example: "GC performed corrective work due to sub non-response"

### Notes & Communication
- **notes** (string, optional): Running log of updates, decisions, disputes
  - Example: "First notice 1/15. Re-notified 1/22. Completed 1/25. Inspector approved."
  - Example: "Sub claims material supplier error. Requested photos from supplier."
  - Example: "Owner approved temporary closeout pending final correction in Phase 2."
  - Supports audit trail and communication history

## Status Workflow

```
┌─────────────────────────────────────────────────────────┐
│                    NORMAL FLOW                           │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  open ──→ in_progress ──→ completed                      │
│   ↓                           ↓                           │
│   └────→ back_charge ────────→┘ (with back-charge amount)│
│                                                           │
│  Any state ──→ disputed (requires resolution)            │
│                  ↓                                        │
│             (return to open/in_progress after resolve)   │
│                                                           │
└─────────────────────────────────────────────────────────┘
```

### Transitions
1. **open → in_progress**: Sub acknowledged and beginning work (via status update)
2. **in_progress → completed**: Work finished, verified by superintendent (date_completed, completed_by set)
3. **open/in_progress → back_charge**: Sub failed to correct; back-charge issued (amount and reason required)
4. **back_charge → completed**: GC corrected work or sub completed after back-charge warning
5. **Any state → disputed**: Item contested (reason required; typically returns to prior state after resolution)

## Completion Statistics Calculations

### By Location
- **Room/Area Completion %** = (completed items in location / total items in location) × 100
- Supports dashboard display: "Room 107: 4/5 items done (80%)"

### By Trade
- **Trade Completion %** = (completed items by trade / total items by trade) × 100
- Supports dashboard display: "Drywall: 12/15 items done (80%)"

### By Priority
- **Priority A Completion %** = (completed A items / total A items) × 100 [**must = 100% for final sign-off**]
- **Priority B Completion %** = (completed B items / total B items) × 100
- **Priority C Completion %** = (completed C items / total C items) × 100 [**may be <100% if owner accepts**]

### Overall Project
- **Overall Completion %** = (total completed items / total punch items) × 100
- **Open Count** = items with status = "open"
- **In Progress Count** = items with status = "in_progress"
- **Back-Charge Count** = items with status = "back_charge"
- **Disputed Count** = items with status = "disputed"

## Bulk Operations

### Bulk Add
User input: *"I found 5 items in Room 107: mud pops, paint scuff, missing outlet, cracked tile, missing grout."*

Process:
1. Extract location: "Room 107"
2. Parse items: Create array of 5 items
3. Prompt for common fields once: Trade (prompt per item or once for all?)
   - If same trade: ask "All drywall?" → apply to all
   - If mixed: ask per item or accept trade in bulk input
4. Auto-assign responsible_sub: resolve from project subs directory
5. Auto-generate IDs: PUNCH-001 through PUNCH-005
6. Set all: date_identified = today, identified_by = current user, status = "open", priority = ?
7. Save to punch list

### Bulk Status Update
User input: *"All drywall items in Room 107 are done. Mark them completed."*

Process:
1. Query punch list: filter by room_number="Room 107" AND trade="Drywall"
2. Display matching items for confirmation
3. Update all: status = "completed", date_completed = today, completed_by = user
4. Save and log bulk update in version_history

## Report Generation

### .docx Format Options

#### Header Section
- Project name and address
- Report date and time generated
- Report type: "Punch List by Area" or "Punch List by Trade"
- Superintendent name and signature line

#### Completion Statistics Section
- **Overall Project**: X% complete, N items remaining, breakdown by status
- **By Area/Location** (if grouped by area):
  ```
  Room 107:        80% (4/5 items) | A: 1/1 | B: 2/2 | C: 1/2
  Conference Room: 100% (3/3)      | A: 0/0 | B: 2/2 | C: 1/1
  ```
- **By Trade** (if grouped by trade):
  ```
  Drywall:         75% (9/12)  | A: 2/2 | B: 5/6 | C: 2/4
  Painting:        90% (9/10)  | A: 0/0 | B: 3/3 | C: 6/7
  ```
- **By Priority**:
  ```
  Priority A (Safety/Code):       100% (8/8) - READY FOR FINAL
  Priority B (Functional):         85% (17/20)
  Priority C (Cosmetic):           70% (14/20) - Optional for closeout
  ```

#### Items by Area (if option selected)
For each location (Room 107, Room 108, etc.):
- **Section Header**: Room/Area name, floor level, grid reference if applicable
- **Items Table**:
  | ID       | Description                | Trade      | Sub            | Status      | Priority | Days Open |
  |----------|----------------------------|------------|----------------|------------|----------|-----------|
  | PUNCH-001| Drywall mud pops NE corner | Drywall    | ABC Drywall    | completed  | B        | 8 days    |
  | PUNCH-002| Paint scuff south wall     | Painting   | Ready Paint    | in_progress| C        | 6 days    |
- **Photos**: Thumbnail or full-size embedded below each item (if available)
- **Notes**: Any back-charge or dispute info, completion dates

#### Items by Trade (if option selected)
For each responsible sub (ABC Drywall, Ready Paint, etc.):
- **Section Header**: Sub name, contact info (if in subs directory), total items assigned
- **Items Table**: Same as above, but sorted by location within trade
- **Summary**: X/Y items completed, back-charge info

#### Back-Charge Summary Section (if back-charges exist)
- **Total Back-Charge Amount**: $XXXX.XX
- **Items Flagged**:
  | ID        | Location   | Description        | Sub             | Amount  | Reason                 |
  |-----------|------------|-------------------|-----------------|---------|------------------------|
  | PUNCH-008 | Room 112   | Electrical hazard  | Smith Electric  | 500.00  | Non-compliance, GC fix |
  | PUNCH-015 | Room 201   | HVAC not functional| ABC Mechanical  | 350.00  | Sub non-response       |

#### Footer
- Project info and contact
- Report generated by: [superintendent name]
- Date/time: [timestamp]
- Page numbers and total pages
- Confidentiality notice if applicable

### Healthcare/Senior Care Special Handling
- **ADA Items**: Flag all Priority A items related to accessibility
  - Examples: Grab bars, accessible routes, door widths, bathroom clearances
  - Separate section: "ADA Compliance Items — 100% Completion Required"
- **Infection Control**: Flag items affecting sanitation
  - Examples: Shower/tub sealing, hand washing stations, sharps containers, supply storage
  - Separate section: "Infection Control Items"
- **Nurse Call System**: Track all nurse call button installations and functionality
  - Separate tracking: "Nurse Call Items — Room-by-Room"
  - Report completion status per room

## Integration Points

### Project Dashboard (`/project-dashboard`)
- **Punch Completion Widget**: Overall % complete, trending over time
- **By Area Chart**: Bar chart showing % complete per room/area
- **By Trade Chart**: Bar chart showing % complete per sub discipline
- **Priority Status**: Count of open A/B/C items
- **Days Open Trending**: Aging analysis; items open >14 days highlighted
- **Back-Charge Summary**: Total amount, count of flagged items

### Daily Report (`/daily-report`)
- **Punch Walk Findings** section: Can reference new items identified during day
  - Example: "Punch walk identified 3 new items in Room 107 (see punch list PUNCH-041, PUNCH-042, PUNCH-043)"
- **Completion Status**: Reference punch completion % for area worked that day
- **Back-Charge Updates**: Log any back-charges issued or resolved

### Closeout Workflow
- **Pre-Final Punch List**: All items listed and assigned; Priority A completion required
- **Final Punch List**: All Priority A done, Priority B >90% complete; Priority C completion optional if owner approved
- **Block Conditions**:
  - Disputed items halt final sign-off
  - Priority A items must = 100%
  - All back-charges must be resolved or owner must accept liability

## Rules & Constraints

1. **No Item Deletion**: Punch items are immutable history; status changes only (set to "completed" or "back_charge")
2. **Priority Cannot Decrease**: Cannot downgrade A → B or B → C once set (can only escalate: C → B → A if severity discovered)
3. **Back-Charge Amount Required**: If status = "back_charge", back_charge_amount must be >0 and back_charge_reason must be provided
4. **Completion Metadata**: Transition to "completed" requires date_completed and completed_by fields populated
5. **Location Required**: Every item must have at least room_number OR building_area defined
6. **Responsible Sub Required**: Every item must reference a valid sub from subs directory
7. **Priority A = 100% for Final**: Project cannot reach final sign-off without all Priority A items completed
8. **Disputes Block Closeout**: Status = "disputed" requires resolution before completion

## Project Intelligence Auto-Population

When project intelligence is loaded, auto-populate punch item fields from the data store to reduce manual entry and improve accuracy.

### Location Auto-Resolution
When the user provides a room number or casual location:
- Read `plans-spatial.json` → `room_schedule` → match `room_number`
- Auto-fill: `building_area` from room's building area, `floor_level` from room's floor level, `grid_reference` from the building area's grid range
- Example: User says "Room 107" → auto-fill building_area="East Wing", floor_level="Level 1", grid_reference="E-G / 3-5"

### Subcontractor Auto-Resolution
When the user names a responsible sub (by name, trade, or casual reference):
- Read `directory.json` → `subcontractors[]` → match by name (partial match) or trade
- Auto-fill: `responsible_sub` with full company name, resolve trade if not provided
- Pull foreman name and phone for the sub notification workflow
- Example: User says "Walker" → resolve to "Walker Construction", trade="Excavation/Sitework", foreman="Mike Johnson"

### Spec Cross-Reference
When a punch item's trade is identified:
- Read `specs-quality.json` → `spec_sections[]` → find sections matching the trade's CSI division
- Include relevant spec section number and acceptance criteria in the punch item notes for context
- Example: trade="Concrete" → pull Section 03 30 00 tolerances and finish requirements

### Drawing Reference
When a punch item location is resolved to a grid/area:
- Read `plans-spatial.json` → `sheet_cross_references.drawing_index[]` → find relevant sheets for that location and discipline
- Include sheet numbers in the punch report for easy plan reference
- Example: Location at Grid E-5, trade="Electrical" → reference sheets E-100, E-101

### Schedule Impact Check
When Priority A items exist:
- Read `schedule.json` → `milestones[]` → check if `final_completion` or `substantial_completion` milestone is at risk
- If open Priority A count > 0 and closeout milestone is within 30 days → flag schedule risk in punch summary
- Include remaining Priority A items in `/morning-brief` when closeout is approaching

## Triggers & Activation Phrases
- "punch list"
- "punch item"
- "punchlist"
- "add punch"
- "punch status"
- "generate punch list"
- "closeout"
- "deficiency"
- "back charge" / "back-charge"
- "punch walk"
- "punch report"

## Version History
- **v1.0.0** (2026-02-17): Initial release. Core CRUD, status workflow, report generation, healthcare specialization.