tasks

name	tasks
description	Track and execute implementation work using Mighty (mt) tasks, with progress comments, linked evidence, recorded decisions, and clean closeout. Use when asked to fix a bug, implement a feature/refactor, or “work through” changes in code while keeping Mighty tasks/specs/decisions updated.

Tasks

Overview

Claim (or create) a Mighty task for the work, keep short progress comments as you go, record decisions when you choose between alternatives, then link evidence and close cleanly. If you create or refine a task, make the task body reviewable and implementation-shaped on its own instead of assuming the next reader will reconstruct the real change from linked specs.

Progressive disclosure rules

• Assume mt prime has already been run for this session; only run it if you’re missing mt conventions/context.
• Treat workstream_ref as the mutable active scope and checkpoint IDs as the rewrite-stable lineage beneath it. If history is rewritten while you work, re-run mt prime as needed and keep using mt flows instead of old SHAs.
• Prefer comments for ephemeral progress and decisions for lasting choices/constraints.
• Keep comments short and high-signal (1–5 bullets or a few sentences).
• When referencing specs/decisions/tasks in descriptions/comments, use [label](cite:<id_prefix>-...) (always include link text).
• Task descriptions are handoff documents. Repeat the small set of contract facts and implementation details a reviewer or worker must not miss, especially the main flow, branches, invariants, and forbidden approaches.

Workflow

0) Start with context (graph first)

Start with:

• mt work / mt mine to see what’s already assigned.
• mt search <keyword> and mt tree to find the relevant spec/decision.
• mt show <id> to read the current intent before changing code.

1) Ensure there is a task for the change

• If the user provides a task ID, use it.
• Otherwise create one, linking it to the source spec/decision with --source:
  • Template: references/task-template.md
• Before you start implementation, check that the task body is self-contained enough for human review and worker handoff:
  • describe the flow in implementation-shaped language or light pseudocode when the work has meaningful branching
  • make reuse/create, load/create, or update/insert rules explicit
  • spell out negative requirements such as “do not add a new persisted actor type”
  • avoid vague acceptance criteria like “support X” when the real requirement is a specific sequence of behavior
• If the task is vague, tighten it before or while claiming it. Related specs/decisions should confirm the task, not substitute for it.

2) Claim the task (start a session)

mt claim <task-id> --reason "Starting work"

3) While working, leave lightweight breadcrumbs

Use comments for progress checkpoints and “why”:

mt comment <task-id> --content "Observed X. Choosing Y because Z. Next: A then B."

Record design decisions when you pick between alternatives:

• mt decision new ... --source <task-id> (creates a spawned edge)
• If you revise an existing decision, use mt decision update ... --reason "..."

Examples: references/progress-comment-examples.md More examples: references/examples.md

4) Link evidence for completed work

When the work is implemented/tested, link evidence (files and/or commits):

• Treat the edge description as a semantic coverage claim. Name the specific guarantee or constraint the artifact covers, not generic labels like Core implementation or Coverage.
• Prefer linking the evidence from the most specific live spec or task that owns that guarantee or constraint. If the parent spec is only an umbrella contract, move the evidence down to the relevant child.

mt link --from <task-or-spec-id> --rel implemented_by --to-type file --to-ref path/to/file.py -d "Implements <specific guarantee or constraint> for <specific flow or state>"

If you need screenshot/doc artifacts in specs/tasks:

mt file upload ./path/to/screenshot.png
# then use returned file_id in markdown:
# ![[file <file_id>]]    (block embed)
# [[file <file_id>]]     (inline mention)
mt link --from <task-or-spec-id> --rel documented_by --to-type file --to-ref mighty-file:<file_id> -d "Screenshot/reference artifact showing <specific guarantee or constraint> for <specific flow or state>"

5) Close the task

mt task close <task-id> --reason "Done" --resolution "What changed and how to verify"

Before closing, compare the implementation against the task body itself, not just your memory of the related specs. If the code shape or key branches diverged from the task in a way a reviewer would care about, either update the task/spec/decision first or surface the mismatch.

6) Session close protocol (before saying “done”)

Run:

mt closeout
mt commit

Treat mt closeout --quiet findings (unlinked decisions/tasks/docs) as required fixes before syncing. Treat the non-quiet changed-file list as advisory and link only files relevant to your work.

Reference templates

• Task structure: references/task-template.md
• Progress comment examples: references/progress-comment-examples.md
• mt shell patterns: references/mt-command-patterns.md
• Good end-to-end examples: references/examples.md