minabot/PRD.md

Minabot — Habit Tracking PRD

Status: Initial product requirements
Date: 2026-09-04

Application intent

Minabot helps people record daily habit progress and understand their consistency through GitHub-style calendar heatmaps. Users can inspect each habit independently and combine selected habits into shared charts.

Individual charts answer, “How much progress did I make on this habit?” Combined charts answer, “How many of the habits due that day did I fully complete?” Partial progress is visible and useful, but does not count as a completed habit in a combined chart.

The primary experience should make logging progress, checking tasks, and reading these calendars simple and quick.

Scope and terminology

Term	Meaning
Habit	A named activity with one completion method and a schedule.
Completion method	A count target, a manual done/not-done checkbox, or completion of all tasks due that day.
Task	A boolean todo belonging to a task-based habit, with its own recurrence rule.
Task occurrence	One scheduled instance of a task for a particular date.
Due habit	A habit included in that date's completion requirements. A task-based habit also needs at least one task due to qualify.
Individual chart	A calendar heatmap showing one habit's daily progress.
Combined chart	A calendar heatmap showing the proportion of included, due habits that are fully complete.
Shade level	One of the chart's discrete visual intensity steps; it is not necessarily a literal opacity percentage.

The initial scope includes habit creation and editing, progress logging, task recurrence, individual and combined charts, historical corrections, and preservation of historical requirements. Notifications, social features, rewards, streak mechanics, integrations, and analytics beyond these charts are outside this PRD's scope.

Confirmed product behavior

1. Habit configuration

Users can create and edit a habit's name, completion method, method-specific settings, and schedule.

Each habit uses exactly one completion method at a time:

Method	User input	Completion rule	Individual chart progress
Count target	Record countable steps toward a target.	The count reaches the target.	Progress toward the target, represented by discrete shades.
Manual checkbox	Mark done or not done.	The checkbox is checked.	Empty or one completed shade.
Tasks	Check individual tasks due that day.	Every task due that day is complete.	Completed due tasks divided by total due tasks, represented by discrete shades.

A habit cannot simultaneously require both a count target and task completion, or an additional manual confirmation. Task-based completion is derived automatically from its due tasks.

For hydration with a target of eight glasses, the individual chart provides eight positive progress steps, plus the empty state. Seven glasses show partial progress; eight glasses complete the habit. Seven glasses never count as a completed habit in a combined chart.

2. Habit and task schedules

Habits can have schedules. Tasks have their own recurrence rules and default to daily recurrence.

Supported scheduling behavior must express:

• Daily recurrence.
• Fixed intervals, such as every three days.
• Specific weekdays, such as every Monday.
• Week intervals with a weekday, such as every two weeks on Wednesday.

Recurrence follows a fixed calendar schedule. Completing an occurrence late, correcting its history, or missing it does not move future scheduled dates. Interval rules need an anchor date so the intended dates are unambiguous.

A task-based habit with no tasks due on a date is not due. It is excluded from that date's combined score; it is not automatically completed.

3. Task occurrence lifecycle

Each scheduled task occurrence has its own completion state. Checking a task completes that occurrence, not future occurrences of the recurring task.

When an occurrence's day ends, an incomplete occurrence expires. Its expiry is recorded, and it does not carry forward as an overdue task. A fresh occurrence is created when the task is next scheduled.

For example, an unchecked Monday task expires after Monday. Tuesday's daily occurrence starts unchecked. Monday's record remains available for inspection and correction.

Historical corrections are allowed after expiry. Correcting Monday must update Monday's habit and chart results without checking Tuesday's occurrence or shifting the recurrence schedule. The record that the original occurrence expired must remain available alongside the correction.

4. Individual habit charts

Each habit has a GitHub-style calendar heatmap with one square per date.

• Count-based habits display progress toward that date's target.
• Manual habits display done or not done.
• Task-based habits display partial progress based on the tasks due on that date.
• Completing two of three due tasks displays partial intensity, while the habit remains incomplete.
• Dates when a habit is not due are visually distinguishable from due dates with zero progress.

Inspecting a square reveals its date, progress, and completion status. The displayed details should expose the underlying values, such as “7 of 8 glasses” or “2 of 3 tasks,” rather than relying on color alone.

5. Combined charts

Users can create combined charts from selected habits. Each included habit has equal weight, regardless of its target or number of tasks.

For a given date:

due = selected habits that are due on that date
completed = habits in due that have met their full completion requirement
score = completed / number of habits in due
shade = the discrete shade level corresponding to score

Partial progress contributes zero completed habits to this calculation. The combined score is not an average of individual progress ratios.

The ratio maps to discrete shade levels. A score of 75% does not require a square rendered at exactly 75% opacity. The palette and thresholds must communicate increasing completion consistently.

Only habits due that day belong in the denominator. As schedules vary, different dates can have different numbers of due habits. Both 1/1 and 4/4 are fully complete and use the full-completion shade; inspecting the square reveals the actual counts.

When no included habits are due, the score is undefined and the square uses a neutral “nothing scheduled” state. It must not appear as either a failed day or a fully completed day.

Due habits	Fully completed	Other progress	Combined result
4	3	Fourth habit is at 7/8.	Score 3/4; use the shade corresponding to 75%.
4	0	All four have partial progress.	Score 0/4; no completion intensity.
2	1	Two additional selected habits are not due.	Score 1/2; the unscheduled habits are excluded.
1	1	All other selected habits are not due.	Full-completion shade; details show 1/1.
0	0	Nothing scheduled.	Neutral state; no completion percentage.

6. Backfilling and corrections

Users can enter missing progress and correct existing progress on previous dates. This includes changing counts, checking or unchecking manual habits, and correcting historical task occurrences.

Edits recalculate the affected individual chart and every combined chart containing the affected habit. Reducing progress below a completion requirement must also remove that habit's completed contribution from combined scores.

Historical logging uses the requirements that applied on the edited date.

7. Changes over time

Changes to a habit's completion method, target, task list, or schedule apply from today onward. Earlier dates retain the requirements that applied at the time.

For example:

• Changing hydration's target from eight glasses to ten does not change whether eight glasses completed yesterday's habit.
• Adding a task today does not make an earlier completed day incomplete.
• Removing a task today does not erase its earlier occurrences or expiry records.
• Changing recurrence today does not add or remove requirements on earlier dates.
• Switching completion methods preserves earlier progress in its original form.

The application must retain enough configuration history to calculate and explain these results. Current configuration alone is insufficient for historical scoring.

Core user flows

1. Create a habit: Enter a name, choose one completion method, configure its target or tasks where applicable, and set its schedule.
2. Log today's progress: See habits and tasks due today, record counts or checkboxes, and see the affected charts update.
3. Review a habit: Inspect its calendar and open a date to see progress and the requirements that applied that day.
4. Combine habits: Select habits for a shared calendar and inspect daily completed-versus-due counts.
5. Correct history: Open a previous date, edit progress against that date's requirements, and see individual and combined results update.
6. Edit a habit: Change its configuration with an explanation that the new requirements apply from today onward.

Proposed defaults and decisions still to finalize

The following details were not explicitly settled in the product discussion. They are recommendations or implementation decisions, separate from the confirmed behavior above.

Topic	Proposed handling / remaining decision
Day boundaries	Use the user's saved timezone and local midnight for scheduling and expiry. The existing project README already anticipates timezone-based daily boundaries. Define how later timezone changes affect dates before implementation.
Habit schedule default	Default new habits to daily; task recurrence is already confirmed to default to daily.
Habit and task schedule interaction	A task occurrence is due only when both its own rule and its parent habit's schedule allow it. Warn about configurations that produce no occurrences; confirm this interaction before implementing the scheduler.
Shade palette	Choose discrete colors and thresholds during visual design. Preserve distinguishable empty, partial, and fully complete states, including all eight positive steps for the hydration example.
Counts beyond the target	Treat reaching or exceeding the target as complete and cap chart intensity at full. Decide whether logging permits over-target values.
Same-day configuration edits	Define what happens to progress already logged today when the completion method or task list changes. Preserve the prior record and make any conversion explicit.
Combined chart membership edits	Decide whether changing selected habits recomputes the chart's entire history or takes effect from today. Historical habit requirements must remain preserved either way.
Future dates	Display upcoming dates separately from missed dates; allow progress logging only for today and past dates by default.
Habit retirement	Define archiving and deletion behavior before adding those controls; historical records should be preserved by default.

Acceptance criteria

1. A habit can use only one completion method at a time, selected during creation or editing.
2. A hydration habit with target eight displays distinct count progress; 7/8 is incomplete and 8/8 is complete.
3. A manual habit has only done and not-done progress states.
4. A task-based habit at 2/3 shows partial individual progress and contributes zero completed habits to a combined chart; 3/3 completes it automatically.
5. A task-based habit with no due tasks is excluded from combined scoring.
6. A combined chart with four due habits and three completed calculates 3/4 and maps it to an available discrete shade.
7. Combined scoring excludes selected habits not scheduled for the inspected date.
8. Dates with nothing due are distinguishable from dates with due habits and zero completions.
9. Combined squares with 1/1 and 4/4 both show full completion, and their details reveal the different counts.
10. Daily, fixed day intervals, weekday rules, and alternate-week weekday rules produce dates based on a fixed schedule, independent of completion timing.
11. An incomplete task occurrence expires at the end of its day, remains recorded, and does not carry forward. The next scheduled occurrence starts fresh.
12. Backfilling and corrections update all affected charts without changing future recurrence dates or other task occurrences.
13. Editing a target, completion method, task list, or schedule today leaves earlier requirements and results unchanged unless the user separately corrects historical progress.
14. Chart details communicate exact counts and status without requiring the user to infer them from shade alone.

Existing application context

The workspace README documents a Bun/Hono backend, React Router client, Drizzle/SQLite persistence, Discord sign-in, and a saved user timezone. This PRD defines the habit-tracking behavior to build on that foundation; it does not claim those habit features already exist.

Habit data and chart selections should belong to the signed-in user. Persistence must represent dated progress, task occurrences and expiry, effective configuration history, and combined chart membership so the confirmed behavior can be implemented reliably.