task-tree

Files (107)

• .gitignore
• SKILL.md
• commands.md · references/
• internals.md · references/
• task-file-contract.md · references/
• _apply_patch.py · scripts/
• _artifacts.py · scripts/
• _checkout_scope.py · scripts/
• _comments.py · scripts/
• _edit_detect.py · scripts/
• _repro.py · scripts/
• _repro_acceptance.py · scripts/
• _repro_builds.py · scripts/
• _repro_provenance.py · scripts/
• _repro_scope.py · scripts/
• _repro_signals.py · scripts/
• _repro_state.py · scripts/
• _step_links.py · scripts/
• _task_dependencies.py · scripts/
• _task_io.py · scripts/
• _task_snapshot.py · scripts/
• _task_validate.py · scripts/
• _worktree_discovery.py · scripts/
• cli.py · scripts/
• conftest.py · scripts/
• dashboard_artifact_workflow.py · scripts/
• plan_dashboard.py · scripts/
• plan_migrate.py · scripts/
• repro_run.py · scripts/
• task_add_result.py · scripts/
• task_check.py · scripts/
• task_comment.py · scripts/
• task_create.py · scripts/
• task_hook.py · scripts/
• task_link.py · scripts/
• task_query.py · scripts/
• task_read.py · scripts/
• task_rename.py · scripts/
• task_update.py · scripts/
• base.html · scripts/templates/
• dashboard.css · scripts/templates/
• dashboard.js · scripts/templates/
• nav_children.html · scripts/templates/
• nav_node.html · scripts/templates/
• node_body.html · scripts/templates/
• summary_bar.html · scripts/templates/
• superra-dashboard-artifact.yml · scripts/templates/
• task_body.html · scripts/templates/
• test_artifact_ui.py · scripts/
• test_cli.py · scripts/
• test_dashboard.py · scripts/
• test_edit_detect.py · scripts/
• test_multi_worktree.py · scripts/
• test_repro.py · scripts/
• test_repro_acceptance.py · scripts/
• test_repro_builds.py · scripts/
• test_repro_engine.py · scripts/
• test_repro_online.py · scripts/
• test_repro_provenance.py · scripts/
• test_repro_runner.py · scripts/
• …and 47 more

SKILL.md (first lines)

# Task Tree

## Core Concepts

- **Task** — an immediate subdirectory of a task directory or the rootless `./superRA` forest that contains `task.md`. `attachments/` is always an asset container, never a task. A leaf task has no child task directories.
- **Filesystem hierarchy is the task hierarchy.** `walk_plan()` discovers children by scanning subdirectories.
- Retained files are companions, not task nodes — classification, placement, and lifecycle in `../using-superra/references/task-companion-files.md`.
- **`depends_on` decides readiness; file dependencies inform.** `depends_on` names sibling directories; a task can start once each one, own or inherited, is `implemented`, `approved`, or `revise`. File edges between steps order builds and are reported as inputs, never gating: [Effective Dependencies](references/task-file-contract.md#effective-dependencies).
- **Parent status rolls up** from children automatically — `approved` only when all active (non-parked) children are `approved`; `archived` and `postponed` children are excluded.
- **DAG order vs. display order.** The dependency DAG controls execution order; numeric directory prefixes (`01-load`, `02-merge`) control display order only. Independent.

## CLI Setup

Bootstrap a fresh project's wrapper from the loaded skill directory (`<skill-dir>` = the directory holding this `SKILL.md`; substitute the real path), then use the wrapper for everything after:

```bash
uv run --script <skill-dir>/scripts/cli.py wrapper init   # writes superRA/superra (planner/main bootstrap)
./superRA/superra wrapper init                             # refresh an existing wrapper; idempotent
```

## Reading the Tree

Run the committed `./superRA/superra` wrapper created above — contributors inside the superRA checkout substitute `uv run --script skills/task-tree/scripts/cli.py`. Every `superra …` example below and in the references denotes it:

```bash
./superRA/superra task tree            # tree with status badges
./superRA/superra task frontier        # ready tasks, each with its inputs whose producer is stale, missing, or failed
./superRA/superra task dag 01-data     # dependency DAG for a subtree (Mermaid)
./superRA/superra task tree --json     # JSON output
./superRA/superra dashboard --no-open  # idempotent; starts or reuses a server and prints this worktree's scoped URL
```

**Deep-link a dashboard task:** append `#/<task-path>` to the scoped URL from `dashboard --no-open`. `<task-path>` is the `task read` locator (no `superRA/` prefix, empty for the tree root). Use the emitted URL as-is — its URL-encoded `?wt=` selector handles worktree-name collisions.

## Task File Format

```yaml
---
title: "Merge with Fund Characteristics"
status: not-started
depends_on:
  - 01-sample-design
---

## Objective

Left join holdings with fund characteristics on fund_id x date.
Use CRSP-style merge conventions. Validate row counts post-merge.

## Results

Left join preserved all 4.7M holdings rows.
Quarterly characteristics were matched to monthly holdings by nearest prior date.

## Review Notes
> [BLOCKING] Inner join used instead of left join
```

Field-by-field anatomy and body-section ownership: `references/task-file-contract.md` §Task Anatomy.

## Routing — operate on the tree

| To do X | See |
|---|---|
| Create / rename / link / move tasks; bulk status propagation; append results programmatically | `references/commands.md` |
| Read or resolve task comments (the read/resolve loop; comments also surface via `superra task read`) | `references/commands.md §Comments` |
| Validate tree structure, fix status inconsistencies, diagnose orphaned `depends_on` entries | `references/commands.md §Diagnostics` |
| Rebuild steps, inspect change impact, or accept reviewed results | [commands.md §Reproduction](references/commands.md#reproduction) |
| Task-file anatomy, fields, status/dependencies, inherited context, results shape, stale-content, figure embedding | `references/task-file-contract.md` |
| Task companion-file classification, placement, reproducibility, promotion, and maturation | `../using-superra/references/task-companion-files.md` |
| Objective writing, task splitting, placement, durable homes, update-task lifecycle, retroactive task-tree creation | `../superplan/references/task-tree-design.md` |
| Migrate legacy `PLAN.md` + `RESULTS.md`, or upgrade `superRA/` v1 → v2 | `references/internals.md §Migration` |
| Dashboard server mechanics (idempotent ensure-running, task URLs, artifact export) | `references/internals.md §Dashboard` |
| Modify the skill itself (data layer, hooks, scripts) | `references/internals.md`; hook coverage details live in `§Hook Architecture` |

Intentional task path changes go through `superra task move` (`task rename` for same-parent compatibility), never raw `mv` / `git mv`. It resolves the fallout — relative Markdown links, root-relative task paths, and sibling-only `depends_on` edges — so run the move directly rather than rewriting them by hand first. Mechanics and cross-parent dependency rules: `references/commands.md §Move / rename a task`.

From FuZhiyu/superRA, MIT.

More from FuZhiyu/superRA