// Manage research and development tasks — add, complete, defer, retire, list, and filter. Use when the user wants to track work items, mark things done, retire outdated tasks, or see what's on the backlog.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | science-tasks |
| description | Manage research and development tasks — add, complete, defer, retire, list, and filter. Use when the user wants to track work items, mark things done, retire outdated tasks, or see what's on the backlog. |
Converted from Claude command /science:tasks.
Before executing any research command:
Resolve project profile: Read science.yaml and identify the project's profile.
Use the canonical layout for that profile:
research → doc/, specs/, tasks/, knowledge/, papers/, models/, data/, code/software → doc/, specs/, tasks/, knowledge/, plus native implementation roots such as src/ and tests/Load role prompt: .ai/prompts/<role>.md if present, else references/role-prompts/<role>.md.
Load the science-research-methodology and science-scientific-writing Codex skills. If native skill loading is unavailable, use codex-skills/INDEX.md to map canonical Science skill names to generated skill files and source paths.
Read specs/research-question.md for project context when it exists.
Load project aspects: Read aspects from science.yaml (default: empty list).
For each declared aspect, resolve the aspect file in this order:
aspects/<name>/<name>.md — canonical Science aspects.ai/aspects/<name>.md — project-local aspect override or additionIf neither path exists (the project declares an aspect that isn't shipped with
Science and has no project-local definition), do not block: log a single line
like aspect "<name>" declared in science.yaml but no definition found — proceeding without it and continue. Suggest the user either (a) drop the
aspect from science.yaml, (b) author it under .ai/aspects/<name>.md, or
(c) align the name with one shipped under aspects/.
When executing command steps, incorporate the additional sections, guidance, and signal categories from loaded aspects. Aspect-contributed sections are whole sections inserted at the placement indicated in each aspect file.
Check for missing aspects: Scan for structural signals that suggest aspects the project could benefit from but hasn't declared:
| Signal | Suggests |
|---|---|
Files in specs/hypotheses/ | hypothesis-testing |
Files in models/ (.dot, .json DAG files) | causal-modeling |
Workflow files, notebooks, or benchmark scripts in code/ | computational-analysis |
Package manifests (pyproject.toml, package.json, Cargo.toml) at project root with project source code (not just tool dependencies) | software-development |
If a signal is detected and the corresponding aspect is not in the aspects list,
briefly note it to the user before proceeding:
"This project has [signal] but the
[aspect]aspect isn't enabled. This would add [brief description of what the aspect contributes]. Want me to add it toscience.yaml?"
If the user agrees, add the aspect to science.yaml and load the aspect file
before continuing. If they decline, proceed without it.
Only check once per command invocation — do not re-prompt for the same aspect if the user has previously declined it in this session.
Resolve templates: When a command says "Read .ai/templates/<name>.md",
check the project's .ai/templates/ directory first. If not found, read from
templates/<name>.md. If neither exists, warn the
user and proceed without a template — the command's Writing section provides
sufficient structure.
Resolve science CLI invocation: When a command says to run science,
prefer the project-local install path: uv run science <command>.
This assumes the root pyproject.toml includes science as a dev
dependency installed via uv add --dev --editable "$SCIENCE_TOOL_PATH"
(the distribution is science; the entry point it installs is science).
If that fails (no root pyproject.toml or science not in dependencies),
fall back to:
uv run --with <science-plugin-root>/science science <command>
Manage the project task queue in tasks/active.md.
the user input specifies the action (add, done, defer, retire, list, show, summary) and any parameters.
Do not use Claude Code's built-in
TaskCreate/TaskUpdate/TaskListtools for science projects. The science task system is the authoritative store: it lives in the repo (tasks/active.md), survives clones, and integrates with the knowledge graph via--related. The Claude-Code task tools maintain a parallel, session-scoped store that is invisible to other agents and creates drift between what the conversation thinks is the task list and what the project actually tracks.
Read tasks/active.md if it exists. If tasks/ directory doesn't exist, create it.
Task IDs are flat local identifiers in the form tNNN: t001, t016, t335, t1000. Do not encode hierarchy, revisions, or follow-up fragments in the ID. Use parent: task:t001 for a local structural parent, and include the parent in related when it should remain visible in graph/search surfaces.
Bare t123 always means a local task. task:t123 is the canonical local task reference. Cross-project task and entity refs use namespace-first form: natural-systems:task:t335, multiple-myeloma:hypothesis:h01, cbioportal:question:q006-ch-priority-gene-completeness.
tasks/archive.md is for historical task aliases only. Use the same ## [tNNN] Title heading shape when old documents still cite a task ID that no longer belongs in tasks/active.md or tasks/done/YYYY-MM.md; include brief metadata such as status: archived and replacement: task:tNNN when there is a successor. Do not use it for current operational task history.
Show active tasks sorted by priority (P0 first). Use:
uv run science tasks list
Filter by related entity or group:
uv run science tasks list --related=topic:lens --group=visualization
Interactively create a task. Ask the user for:
<kind>:<slug> such as hypothesis:h01 or task:t016; cross-project refs use <project-id>:<kind>:<slug> such as natural-systems:task:t335.Then run:
uv run science tasks add "<title>" --type=<type> --priority=<priority> [--related=<ref>...] [--group=<group>]
Mark a task complete. Optionally ask for a completion note.
uv run science tasks done <task_id> [--note="<note>"]
Defer a task. Ask for a reason.
uv run science tasks defer <task_id> [--reason="<reason>"]
Close a task that is no longer a priority (not completed, just abandoned). Moves to done/ archive with retired status.
uv run science tasks retire <task_id> [--reason="<reason>"]
Block a task by one or more typed entity references (<kind>:<local-id>).
Refs must resolve to known local entities. Repeatable.
--force records the ref even if the entity is not yet known (e.g.
you plan to create the dataset shortly). The unresolved reference will
be flagged by science graph audit.science tasks fix-blockers to retype existing
legacy blockers.Show per-blocker readiness for a task. --format json for scripting.
Interactive sweep to retype legacy untyped blockers in tasks/active.md.
--dry-run lists what would change without modifying files.
Remove all blockers and set status to active.
Update task fields. Supports --related (repeatable) and --group (single value).
Show full details of a single task.
Show task counts by status, type, priority, and group.
Pass through to science tasks:
uv run science tasks <action> [args...]
| Status | Meaning |
|---|---|
proposed | Identified but not started |
active | Currently being worked on |
blocked | Waiting on another task |
deferred | Deprioritized, may return |
done | Completed successfully |
retired | Closed without completion — no longer a priority |
When working through tasks, follow these principles:
tasks blockers <task_id> to inspect per-blocker readiness (e.g., embargoed datasets, incomplete workflow runs). Run science-tasks list --status=active to see what's actionable overall.science tasks edit <id> --status=blocked. This prevents repeating the same failed approach.AGENTS.md before executing. The project's operational guide may document known issues, environment constraints, or workarounds discovered in previous sessions.active when starting, done when complete. Don't leave tasks in ambiguous states.retire instead of deleting. This preserves the decision record.related for cross-cutting connections. Link tasks to hypotheses, themes, methods, or other entities with --related (e.g., --related=method:umap). Related entries become edges in the knowledge graph, and the same entity can appear across multiple groups. Use the meta: prefix for annotations you want to keep visible but exclude from the KG (e.g., --related=meta:phase3b).Commit: git add tasks/ && git commit -m "tasks: <brief description of change>"