Build the Right Thing First

gemini "@GEMINI.md Write a Product Requirements Document for a Recurring Tasks feature.

The feature: tasks that auto-recreate on a schedule after they are completed.

Include:
1. Problem Statement
2. Goals and Non-Goals
3. User Personas (who needs this?)
4. Functional Requirements (numbered, testable)
5. Acceptance Criteria for each requirement
6. Out of Scope items
7. Open Questions

Be specific to TaskFlow's existing data model. Reference actual fields
from models.py where relevant."

# Product Requirements Document: Recurring Tasks

## Problem Statement
TaskFlow users currently manage repetitive obligations (weekly team reports,
monthly expense submissions, daily standup notes) by manually recreating
identical tasks after completion. This creates cognitive overhead and risks
tasks being forgotten.

## Goals
- Users can mark any Task as recurring with a defined schedule
- When a recurring task is completed, a new instance auto-spawns
- Users can pause, modify, or delete a recurrence without losing task history

## Non-Goals (Out of Scope v1)
- Email/push notifications when a recurrence triggers
- Sharing recurrences across users
- Calendar integration

## Functional Requirements
FR-1: A user SHALL be able to set a recurrence on any existing task via
      POST /tasks/{id}/recurrence
FR-2: The recurrence SHALL support three schedule types:
      daily, weekly (specific days), monthly (specific date)
FR-3: When a task with active recurrence is marked completed, the system
      SHALL automatically create a new task with identical fields within
      60 seconds
FR-4: A user SHALL be able to retrieve the recurrence settings for a task
      via GET /tasks/{id}/recurrence
FR-5: A user SHALL be able to delete a recurrence, which stops future
      auto-spawn but does not affect existing tasks

## Acceptance Criteria
FR-1 AC: POST /tasks/42/recurrence with {"schedule_type": "daily"} returns
         201 with the recurrence object; GET /tasks/42 shows has_recurrence: true
FR-3 AC: Mark task 42 completed at T=0; by T=60s a new task exists with
         the same title, description, priority, and owner_id

## Open Questions
- OQ-1: Who triggers the spawn — a background scheduler or an endpoint call?
- OQ-2: What timezone does "daily" mean? User's timezone or UTC?
- OQ-3: Should the spawned task inherit the original task's tags?

gemini "@GEMINI.md @spec/recurring-tasks-prd.md
Convert the Recurring Tasks PRD into 5-8 user stories.
For each story:
- Write it in 'As a [user] I want [goal] so that [benefit]' format
- Score it on the INVEST criteria (I/N/V/E/S/T — each: Pass/Partial/Fail)
- List 3 acceptance criteria
- Estimate story points (1/2/3/5/8)
- Flag any dependencies on other stories"

## Story 1 — Set a Recurrence
As a TaskFlow user, I want to attach a recurring schedule to any of my tasks
so that I don't have to manually recreate repetitive tasks.

INVEST: I=Pass, N=Pass, V=Pass, E=Pass, S=Pass, T=Pass

Acceptance Criteria:
  AC1: POST /tasks/{id}/recurrence with valid schedule returns 201
  AC2: GET /tasks/{id} returns has_recurrence: true
  AC3: POST to a non-existent task_id returns 404

Story Points: 3
Dependencies: None (builds on existing Task CRUD)

---
## Story 2 — View Recurrence Settings
As a user, I want to retrieve the recurrence settings for a task
so that I can verify what schedule is active.

INVEST: I=Pass, N=Pass, V=Pass, E=Pass, S=Pass, T=Pass

Acceptance Criteria:
  AC1: GET /tasks/{id}/recurrence returns recurrence object for recurring task
  AC2: GET /tasks/{id}/recurrence returns 404 for non-recurring task
  AC3: Only the task owner can view recurrence settings (401 otherwise)

Story Points: 1
Dependencies: Story 1

---
## Story 3 — Auto-Spawn on Completion
As a user, I want a new task to be automatically created when I complete
a recurring task so that the next instance appears without manual work.

INVEST: I=Partial (depends on scheduler), N=Pass, V=Pass, E=Partial, S=Fail, T=Pass

Story Points: 8
Dependencies: Stories 1, 2, and background scheduler (OQ-1 must be resolved)
NOTE: S=Fail — this story is too large. Split into 3a (spawn logic) and
      3b (background scheduler integration)

gemini "@models.py @schemas.py @routers/tasks.py
Identify gaps between the current TaskFlow implementation and the
Recurring Tasks feature described here:

Feature: Tasks that auto-recreate on a schedule when completed.
- New endpoint: POST /tasks/{id}/recurrence
- New endpoint: GET /tasks/{id}/recurrence
- New endpoint: DELETE /tasks/{id}/recurrence
- Background spawn: when Task.completed = True, create new Task

For each gap:
1. Which file needs to change
2. What specifically needs to be added or modified
3. Risk level (Low/Medium/High) and reason"

## Gap Analysis: TaskFlow → Recurring Tasks Feature

### models.py
GAP-1: No RecurringTask model exists
  - Add: class RecurringTask(Base) with fields:
    task_id (FK → tasks.id), schedule_type (str), interval_value (int),
    next_run_at (DateTime), is_active (bool), created_at (DateTime)
  - Also add: Task.recurrence = relationship("RecurringTask", ..., uselist=False)
  Risk: Medium — requires Alembic migration; existing rows unaffected

GAP-2: Task model has no completion event/hook
  - Task.completed is a plain Boolean; there is no SQLAlchemy event listener
  - A scheduler polling Task.completed changes is required
  Risk: High — architectural decision (polling vs. event sourcing)

### schemas.py
GAP-3: No RecurringTaskCreate, RecurringTask response schemas
  - Add: RecurringTaskCreate(schedule_type, interval_value)
  - Add: RecurringTask(id, task_id, schedule_type, next_run_at, is_active)
  - Pattern to follow: existing Tag / TagCreate pair (lines 7-16)
  Risk: Low

### routers/tasks.py
GAP-4: No recurrence endpoints in tasks router
  - Add: POST /tasks/{id}/recurrence
  - Add: GET /tasks/{id}/recurrence
  - Add: DELETE /tasks/{id}/recurrence
  - Pattern: follow existing get_task() / update_task() auth pattern
  Risk: Low

### NEW FILE REQUIRED
GAP-5: No background scheduler exists
  - Need: APScheduler or similar; polls for tasks where
    completed=True AND recurrence.is_active=True AND next_run_at <= now()
  - Or: use FastAPI startup event to launch scheduler thread
  Risk: High — requires new dependency; impacts app startup

# Assume you have a spec file at docs/recurring-tasks-spec.md
gemini "@GEMINI.md @docs/recurring-tasks-spec.md
Review this requirements document as a senior engineer.
Identify:
1. Ambiguous requirements (could be interpreted multiple ways)
2. Missing edge cases (what happens when X fails?)
3. Untestable requirements (no pass/fail criteria)
4. Contradictions with the existing codebase
5. Security concerns (auth, data isolation, rate limits)

For each issue, quote the relevant line and suggest a fix."

gemini "@GEMINI.md @spec/recurring-tasks-prd.md
List every edge case that is NOT addressed in this PRD.
Focus on:
- What happens when the task is deleted while a recurrence is active?
- What happens when next_run_at is in the past (server was down)?
- What if a user sets daily recurrence on a task with a past due_date?
- What if the spawned task should inherit tags — but a tag was deleted?

For each edge case: state the scenario, the expected behavior, and
whether it needs a new requirement or just a code comment."

gemini "@GEMINI.md @spec/recurring-tasks-prd.md
Output the Recurring Tasks feature spec as valid JSON only.
No markdown, no explanation — just the JSON object.

Use this structure:
{
  'feature': string,
  'version': '1.0',
  'user_stories': [{ 'id': string, 'story': string, 'points': number, 'acceptance_criteria': string[] }],
  'new_models': [{ 'name': string, 'fields': object, 'relationships': string[] }],
  'new_endpoints': [{ 'method': string, 'path': string, 'auth': boolean, 'request_body': object, 'response': object }],
  'acceptance_criteria': string[],
  'out_of_scope': string[],
  'open_questions': string[]
}" > spec/recurring-tasks.json

{
  "feature": "Recurring Tasks",
  "version": "1.0",
  "user_stories": [
    {
      "id": "US-1",
      "story": "As a user I want to set a recurring schedule on a task so that it auto-recreates on completion",
      "points": 3,
      "acceptance_criteria": [
        "POST /tasks/{id}/recurrence returns 201 with recurrence object",
        "GET /tasks/{id} shows has_recurrence: true",
        "POST to non-existent task returns 404"
      ]
    }
  ],
  "new_models": [
    {
      "name": "RecurringTask",
      "fields": {
        "id": "Integer PK",
        "task_id": "Integer FK tasks.id UNIQUE",
        "schedule_type": "String (daily|weekly|monthly)",
        "interval_value": "Integer nullable",
        "next_run_at": "DateTime timezone=True",
        "is_active": "Boolean default=True",
        "created_at": "DateTime server_default=func.now()"
      },
      "relationships": ["Task.recurrence backref via task_id"]
    }
  ],
  "new_endpoints": [
    {
      "method": "POST",
      "path": "/tasks/{task_id}/recurrence",
      "auth": true,
      "request_body": { "schedule_type": "string", "interval_value": "int?" },
      "response": { "status": 201, "body": "RecurringTask schema" }
    },
    {
      "method": "GET",
      "path": "/tasks/{task_id}/recurrence",
      "auth": true,
      "request_body": null,
      "response": { "status": 200, "body": "RecurringTask schema" }
    },
    {
      "method": "DELETE",
      "path": "/tasks/{task_id}/recurrence",
      "auth": true,
      "request_body": null,
      "response": { "status": 204, "body": null }
    }
  ],
  "out_of_scope": ["Notifications", "Cross-user sharing", "Calendar integration"],
  "open_questions": [
    "OQ-1: Background scheduler vs endpoint-triggered spawn?",
    "OQ-2: User timezone vs UTC for schedule evaluation?",
    "OQ-3: Should spawned task inherit parent's tags?"
  ]
}