Tasks, projects, sprints, and initiatives

Overview

The work-management primitives in Vigilo follow a familiar hierarchy:

Task (TASK-NNNN) — A unit of work. May stand alone or be linked to a project, sprint, milestone, change, incident, or postmortem.
Project (PROJ-NNN) — A bounded effort with a lead, dates, members, milestones, and a backlog of tasks.
Sprint — A time-boxed slice of a project with capacity, committed points, and a burndown chart.
Milestone — A dated checkpoint within a project.
Initiative — A multi-project portfolio container for strategic rollups.

All five live under Work in the sidebar at /ws/{slug}/projects and /ws/{slug}/tasks. The detail surfaces are tightly cross-linked: a task on a change-implementation runbook shows its parent change, a postmortem action item shows its source postmortem, a sprint shows its committed and completed points.

Why it exists

Most of the work that flows through Vigilo isn't a change or an incident — it's the day-to-day grind that prevents changes and incidents. The task and project model gives that work a first-class home alongside the operational artifacts so the team's full picture (engineering velocity, postmortem follow-through, project health) lives in one place.

Key concepts

Task — Has key, title, description, status (todo, in_progress, blocked, done, cancelled), priority, assignee, due_date, estimated_hours, logged_hours, story_points. Cross-app links are all optional and nullable: change, project, sprint, milestone, incident, source_postmortem.
Parent / subtasks — Self-FK on Task.parent. Cascade-delete: removing a parent removes its subtasks (flatten beforehand if you want to keep them).
blocks (M2M) — Task.blocks is the directed dependency edge: this task blocks those tasks. Reverse accessor blocked_by gives the inverse. The critical path computation (WB.22) walks this graph to surface the longest blocking chain in a project.
watchers — Task.watchers M2M to UserProfile. Independent of assignee — a stakeholder who wants notifications without owning the work.
source_postmortem — Optional FK set when a Task was materialised by Postmortem.publish() (WB.31). Lets the postmortem detail render a "Follow-up tasks" panel and lets re-publishing stay idempotent.
Project.health_score — 0-100 heuristic from completion ratio. Cancelled projects score 0; completed score 100; projects with no tasks default to 60.
Sprint — Has capacity_points, committed_points (snapshotted at start()), completed_points (snapshotted at complete()), velocity (kept for back-compat with the velocity chart), retrospective_notes.
RecurringTaskTemplate — Scheduled task spawn. Has interval (daily, weekly, biweekly, monthly, quarterly), next_run_at, last_run_at, run_count. The Celery beat vigilo.tasks.materialize_recurring scans each morning; templates whose next_run_at has passed produce a new Task and advance the schedule.
TimeEntry — Hours-logged record with optional links to a task, change, or incident. Powers the actuals vs estimates report and the workspace-level effort distribution dashboard.

Common workflows

Creating a task

Click New task from anywhere in the workspace (the keyboard shortcut is t).
Fill in title, optional description, priority, assignee, due date. Estimate in hours or story points.
Link the task to a project, sprint, milestone, change, or incident if it belongs to one. None of these are required — orphan tasks are fine.
Save. The task gets a workspace-sequential key (TASK-0042).

Building a dependency graph

Open a task. In the Dependencies section, click Add blocker to say "this task is blocked by another" or Add blocking to say "this task blocks another".
The task detail page renders the local dependency graph as a small interactive view; the project detail's Critical path tab walks the entire project's graph and highlights the longest chain (WB.22). Late tasks on the critical path are flagged red.

Running a sprint

From the project, click Sprints → New sprint. Pick name, goal, start_date, end_date, and capacity_points.
Drag backlog tasks onto the sprint until you've committed roughly your capacity. Tasks on the sprint show their story_points summed against capacity in the sprint header.
Click Start. Sprint.start() snapshots committed_points (defaults to capacity_points if you haven't moved every task individually) and stamps start_date if it was empty.
Burn down through the sprint. The Burndown tab (WB.23) plots ideal vs actual point completion daily.
Click Complete at the end. The completion dialog asks for completed_points and a retrospective blurb. Both are recorded; velocity is set from completed_points so the cross-sprint velocity chart updates.

Cloning a project from a template

Go to Projects → New → From template. Pick a source project (any project in the workspace, even an archived one, can serve as a template).
The clone (WB.9) copies the project's milestones, member roster (roles intact), and task scaffolding. It does not copy completed tasks, time entries, or status updates.
Edit the cloned project's name, lead, and dates. Save.

Configuring a recurring task

Go to Tasks → Recurring → New template.
Fill title, default assignee, priority, and interval. Pick the first next_run_at.
Save. The Celery sweep materialises a new Task each cycle. Holidays are respected (WB.10): if next_run_at falls on a workspace holiday, the materialisation is skipped and rescheduled to the next business day.

Recording actuals

From any task, click Log time. Enter hours and date. The entry shows in the project's Effort tab as actuals against the task's estimated_hours. Time can also be logged against a change or incident directly when the work doesn't fit into a task.

Permissions

Viewers can read tasks, projects, sprints, milestones, and initiatives.
Engineers / project members can create tasks, edit tasks assigned to them or in projects they're a member of, log time, and update status.
Project leads can edit project metadata, create sprints, and archive the project.
Admins / owners can edit anything, force-reassign, and delete.

Troubleshooting

The critical path doesn't include my task — The task isn't blocking anything that lands on the path. The critical path is the longest blocking chain, not the longest list of tasks. Add an outbound blocks edge if the task is genuinely a prerequisite.

Sprint velocity looks wrong — velocity is only updated on complete(). A sprint still in active won't appear in the velocity chart. Older sprints created before the points fields existed may also have null velocity; they're plotted as zero.

A recurring task didn't spawn this morning — Either the template is is_active=False, next_run_at is still in the future (check the timezone), today is a workspace holiday and the skip-on-holiday rescheduler caught it, or the Celery beat isn't running. The template detail shows last_run_at and run_count for diagnostic.

Postmortem action items didn't show as tasks — The postmortem needs to be published (not just saved as a draft). Re-publish; the materialiser is idempotent — existing linked tasks are not duplicated.

Time entry doesn't show on the task — Confirm the entry's task FK is set. Entries logged against change or incident only without a task FK appear in those entities' effort tabs, not on tasks.