Work Phasing Skill

Read all .hackathon/ documents: STATE.md, IDEA-FINAL.md, ARCHITECTURE.md, STACK.md, all specs in specs/, and all contracts.

Hard gate: Breakdown and scaffold must both be complete.

Phasing Philosophy

The goal is NOT to plan every minute. The goal is to:

1. Make sure nobody is blocked or idle
2. Make sure the most critical path is started first
3. Make sure integration happens at defined points, not at the chaotic end
4. Make sure the demo is always in a demoable state
5. Enable /start-work to recommend parallel execution when tasks are independent

Every task must include a Files: field listing the directories and files it touches. This is what /start-work uses to determine whether two tasks can safely run in parallel (different files = safe) or must be sequential (overlapping files = sequential). Be specific — apps/api/src/routes/documents.ts is useful; apps/api/ is too broad.

Time Budget

From STATE.md, calculate remaining time. Reserve:

• 2 hours: final demo prep, deployment, buffer
• 1 hour: integration testing
• 30 min: mid-point sync (sync task boards, resolve blockers)

Remaining time = coding time.

Phasing Structure

Development Phase 1: Foundation (First 30% of coding time)

Goal: Each person has something working independently.

Dev tasks in this phase should:

• Have ZERO dependencies on each other
• Produce testable, visible output
• Follow the contracts exactly
• Use mocks for any dependency that isn't ready

Non-dev tasks in this phase:

• PM: Refine demo script based on what's actually getting built, prepare pitch outline, set up demo environment (screen sharing, etc.)
• Data: Prepare test data sets, define validation criteria, set up any data pipelines

Gate: Phase 1 → Phase 2
All Phase 1 tasks complete. Both devs have working, independent pieces. Quick 15-min sync to verify contracts are being followed.

Development Phase 2: Integration + Features (Next 50% of coding time)

Goal: Pieces start connecting. Primary user flow works end-to-end.

Dev tasks in this phase:

• Integration points (frontend calls real backend, not mocks)
• Secondary features from MVP scope
• Error handling for the demo-critical paths
• Real data flowing through the system

Non-dev tasks:

• PM: Test the integrated product, log issues, update demo script, start recording backup demo
• Data: Validate with real-ish test data, verify outputs, help with data display/formatting

Gate: Phase 2 → Phase 3
Primary demo flow works end-to-end with real (or realistic) data. Demo script validated against actual product.

Development Phase 3: Polish + Stretch (Final 20% of coding time)

Goal: Make it shine. Stretch goals if there's time.

Dev tasks:

• Visual polish (design system components applied everywhere)
• Loading states, error states, empty states
• Stretch features (ONLY if core demo is solid)
• Bug fixes from testing

Non-dev tasks:

• PM: Final demo script, pitch rehearsal, slides if needed
• Data: Final data validation, analytics view if applicable

Task Board Format

For each person, create .hackathon/tasks/[slug].md where slug matches their role (dev-1, dev-2, pm, data):

---
owner: [name]
slug: [dev-1 | dev-2 | pm | data]
role: [dev | pm | data]
last-synced: [timestamp]
---

# [Name]'s Task Board

## Phase 1 — Foundation
- [ ] [priority] `P1-D1-01` [Critical task] — [description] — Est: [hours]
      Dependencies: none
      Files: [directories/files this task creates or modifies]
      Outputs: [what this produces — the deliverable]
      Contract: [which contract section this implements]
- [ ] [priority] `P1-D1-02` [Important task] — [description] — Est: [hours]
      Dependencies: none
      Files: [directories/files]
- [ ] [priority] `P1-D1-03` [Nice-to-have] — [description] — Est: [hours]
      Files: [directories/files]

## Phase 2 — Integration
- [ ] [priority] `P2-D1-01` [Task] — Dependencies: P1-D2-01
- [ ] [priority] `P2-D1-02` [Task] — Dependencies: none (parallel work)

## Phase 3 — Polish
- [ ] [priority] `P3-D1-01` [Task] — Dependencies: P2-D1-01, P2-D1-02
- [ ] [priority] `P3-D1-02` [Stretch task] — Only if Phase 2 is done

## Gate Checklist
### Phase 1 → Phase 2
- [ ] [My deliverable for the gate check]
- [ ] [Contract verification]

### Phase 2 → Phase 3
- [ ] [Integration working]
- [ ] [Demo flow validated]

Task Status Key

Tasks use markdown checkboxes with extended states (used by /start-work and throughout development):

• [ ] — Not started (available to pick up)
• [>] — In progress (actively being worked on)
• [x] — Complete
• [-] — Cut / descoped (removed by /rescope)

Priority key: 🔴 Critical (demo depends on this) | 🟡 Important (quality depends on this) | 🟢 Nice-to-have

Task ID Format

Every task has a stable ID in the format P{phase}-{slug}-{number}:

• P1-D1-03 = Development Phase 1, Dev 1, Task 3
• P2-PM-01 = Development Phase 2, PM, Task 1
• P1-DA-02 = Development Phase 1, Data, Task 2

These IDs are used for cross-references in the Dependencies: field. Dependencies must use task IDs, not task names or descriptions:

Dependencies: P1-D2-01, P1-D1-02

This prevents ambiguity when /start-work checks whether a task is blocked.

Dependency Visualization

Create a text-based dependency graph in PLAN.md:

Phase 1 (Parallel)                    Phase 2 (Integration)              Phase 3 (Polish)
├─ Dev1: Backend API routes ──────┐
│                                  ├── Dev1: Integration + AI pipeline ── Dev1: Polish + stretch
├─ Dev2: Frontend pages + mock ───┘
│                                  ├── Dev2: Real API calls + forms ──── Dev2: Error states + UX
├─ PM: Demo script + pitch ───────── PM: Test + iterate demo ─────────── PM: Final demo + slides
└─ Data: Test data + schemas ─────── Data: Validate real data ─────────── Data: Analytics view
                                  │
                              [SYNC POINT]
                           15-min standup
                        Verify contracts match

Output

• .hackathon/PLAN.md — master plan with dependency graph
• .hackathon/tasks/[slug].md — per-person task boards (dev-1, dev-2, pm, data)
• Updated STATE.md
• Log to changelog
• Print summary: "Work is phased. [N] tasks across [people]. Phase 1 starts now — everyone can work in parallel. First sync point in [X] hours."