HouseHoldKeaper/.planning/REQUIREMENTS.md

# Requirements: HouseHoldKeaper

**Defined:** 2026-03-15
**Core Value:** Users can see what needs doing today, mark it done, and trust the app to schedule the next occurrence — without thinking about it.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Room Management

- [x] **ROOM-01**: User can create a room with a name and an icon from a curated Material Icons set
- [x] **ROOM-02**: User can edit a room's name and icon
- [x] **ROOM-03**: User can delete a room with confirmation (cascades to associated tasks)
- [x] **ROOM-04**: User can reorder rooms via drag-and-drop on the rooms screen
- [x] **ROOM-05**: User can view all rooms as cards showing name, icon, due task count, and cleanliness indicator

### Task Management

- [x] **TASK-01**: User can create a task within a room with name, optional description, frequency interval, and effort level
- [x] **TASK-02**: User can edit a task's name, description, frequency interval, and effort level
- [x] **TASK-03**: User can delete a task with confirmation
- [x] **TASK-04**: User can set frequency interval from: daily, every 2 days, every 3 days, weekly, biweekly, monthly, every 2 months, quarterly, every 6 months, yearly, or custom (every N days)
- [x] **TASK-05**: User can set effort level (low / medium / high) on a task
- [x] **TASK-06**: User can sort tasks within a room by due date (default sort order)
- [x] **TASK-07**: User can mark a task as done via tap or swipe, which records a completion timestamp and auto-calculates the next due date based on the interval
- [x] **TASK-08**: Overdue tasks are visually highlighted with distinct color/badge on room cards and in task lists

### Task Templates

- [x] **TMPL-01**: When creating a room, user can select from bundled German-language task templates appropriate for that room type
- [x] **TMPL-02**: Preset room types with templates include: Küche, Badezimmer, Schlafzimmer, Wohnzimmer, Flur, Büro, Garage, Balkon, Waschküche, Keller, Kinderzimmer, Gästezimmer, Esszimmer, Garten/Außenbereich

### Daily Plan

- [ ] **PLAN-01**: User sees all tasks due today grouped by room on the daily plan screen (primary/default screen)
- [ ] **PLAN-02**: Overdue tasks appear in a separate highlighted section at the top of the daily plan
- [ ] **PLAN-03**: User can preview upcoming tasks (tomorrow / this week)
- [ ] **PLAN-04**: User can swipe-to-complete or tap checkbox to mark tasks done directly from the daily plan view
- [ ] **PLAN-05**: User sees a progress indicator showing completed vs total tasks for today (e.g. "5 of 12 tasks done")
- [ ] **PLAN-06**: When no tasks are due, user sees an encouraging "all clear" empty state

### Cleanliness Indicator

- [ ] **CLEAN-01**: Each room card displays a cleanliness indicator derived from the ratio of overdue tasks to total tasks in that room

### Notifications

- [ ] **NOTF-01**: User receives a daily summary notification showing today's task count at a configurable time
- [ ] **NOTF-02**: User can enable/disable notifications in settings

### Theme & UI

- [x] **THEME-01**: App supports light and dark themes, following the system setting by default
- [x] **THEME-02**: App uses a calm Material 3 palette with muted greens, warm grays, and gentle blues

### Foundation

- [x] **FOUND-01**: App uses Drift for local SQLite storage with proper schema migration workflow
- [x] **FOUND-02**: App uses Riverpod 3 for state management with code generation
- [x] **FOUND-03**: App uses localization infrastructure (ARB files + AppLocalizations) with German locale, even though only one language ships in v1
- [x] **FOUND-04**: Bottom navigation with tabs: Home (Daily Plan), Rooms, Settings

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### v1.1 — Near-Term

- **EXPORT-01**: User can export all data as JSON file
- **EXPORT-02**: User can import data from a JSON file
- **I18N-01**: App supports English as a second language
- **PHOTO-01**: User can add a cover photo to a room from camera or gallery
- **HIST-01**: User can view a completion history log per task (scrollable timeline of completion dates)
- **SORT-01**: User can sort tasks by alphabetical order, interval length, or effort level (in addition to due date)

### v1.2 — Medium-Term

- **PROJ-01**: User can create one-time organization projects with sub-task steps
- **PROJ-02**: User can attach before/after photos to a project
- **PROF-01**: User can create named local profiles for household members
- **PROF-02**: User can assign tasks to one or more profiles
- **PROF-03**: User can enable task rotation (round-robin) for shared recurring tasks
- **PROF-04**: User can filter the daily plan view by profile ("My tasks" vs "All tasks")
- **WIDG-01**: Home screen widget showing today's due tasks and overdue count
- **CAL-01**: User can view a weekly overview with task load per day
- **CAL-02**: User can view a monthly calendar heatmap showing task density
- **VAC-01**: User can pause/freeze all task due dates during vacation and resume on return

### v2.0 — Future

- **STAT-01**: User can view completion rate (% on time this week/month)
- **STAT-02**: User can view streak of consecutive days with all tasks completed
- **STAT-03**: User can view per-room health scores over time
- **ONBRD-01**: First-launch wizard walks user through creating first room and adding tasks
- **COLOR-01**: User can pick a custom accent color for the app theme
- **SYNC-01**: User can optionally sync data via self-hosted infrastructure
- **TABLET-01**: App provides a tablet-optimized layout with adaptive breakpoints
- **NOTF-03**: Optional evening nudge notification if overdue tasks remain

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| User accounts & cloud sync | Local-only by design — zero backend, zero data leaves device |
| Leaderboards & points ranking | Anti-feature — gamification causes app burnout and embeds unequal labor dynamics |
| Subscription model / in-app purchases | Free forever by design — paywalls are the #2 complaint in chore app reviews |
| Family profile sharing across devices | Single-device app; cross-device requires cloud infrastructure |
| AI-powered task suggestions | Requires network/ML; overkill for personal app with curated templates |
| Per-task push notifications | Causes notification fatigue; daily summary is more effective for habit formation |
| Focus timer / Pomodoro | Not a productivity timer app; out of domain |
| Firebase or any Google cloud services | Contradicts local-first, privacy-first design |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| FOUND-01 | Phase 1: Foundation | Complete |
| FOUND-02 | Phase 1: Foundation | Complete |
| FOUND-03 | Phase 1: Foundation | Complete |
| FOUND-04 | Phase 1: Foundation | Complete |
| THEME-01 | Phase 1: Foundation | Complete |
| THEME-02 | Phase 1: Foundation | Complete |
| ROOM-01 | Phase 2: Rooms and Tasks | Complete |
| ROOM-02 | Phase 2: Rooms and Tasks | Complete |
| ROOM-03 | Phase 2: Rooms and Tasks | Complete |
| ROOM-04 | Phase 2: Rooms and Tasks | Complete |
| ROOM-05 | Phase 2: Rooms and Tasks | Complete |
| TASK-01 | Phase 2: Rooms and Tasks | Complete |
| TASK-02 | Phase 2: Rooms and Tasks | Complete |
| TASK-03 | Phase 2: Rooms and Tasks | Complete |
| TASK-04 | Phase 2: Rooms and Tasks | Complete |
| TASK-05 | Phase 2: Rooms and Tasks | Complete |
| TASK-06 | Phase 2: Rooms and Tasks | Complete |
| TASK-07 | Phase 2: Rooms and Tasks | Complete |
| TASK-08 | Phase 2: Rooms and Tasks | Complete |
| TMPL-01 | Phase 2: Rooms and Tasks | Complete |
| TMPL-02 | Phase 2: Rooms and Tasks | Complete |
| PLAN-01 | Phase 3: Daily Plan and Cleanliness | Pending |
| PLAN-02 | Phase 3: Daily Plan and Cleanliness | Pending |
| PLAN-03 | Phase 3: Daily Plan and Cleanliness | Pending |
| PLAN-04 | Phase 3: Daily Plan and Cleanliness | Pending |
| PLAN-05 | Phase 3: Daily Plan and Cleanliness | Pending |
| PLAN-06 | Phase 3: Daily Plan and Cleanliness | Pending |
| CLEAN-01 | Phase 3: Daily Plan and Cleanliness | Pending |
| NOTF-01 | Phase 4: Notifications | Pending |
| NOTF-02 | Phase 4: Notifications | Pending |

**Coverage:**
- v1 requirements: 30 total
- Mapped to phases: 30
- Unmapped: 0

---
*Requirements defined: 2026-03-15*
*Last updated: 2026-03-15 after roadmap creation*