# Discovery Tree

> Visualizes tasks as a Discovery Tree using Mermaid diagrams. Use when planning or tracking multi-step work with parent and child task relationships.

- Skill: `gary-ash/discovery-tree` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gary-ash/discovery-tree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gary-ash/discovery-tree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: gary-ash (https://skillmd.com/u/gary-ash)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gary-ash/discovery-tree

---


# Discovery Tree

STARTER_CHARACTER = 🌲

## Description

Visualize tasks as a Discovery Tree, where subtasks are child nodes.

## Steps

### Step 1: Open File

Open `discovery-tree.md`.

If it doesn't exist, create it:
- Ask user "What is the project title?" and wait for input.
- Then ask user: "What is the parent task?"
- Use template in `references/template-discovery-tree.md`, replacing `parent-node` and `Parent Task` with parent task

### Step 2: Constraint

Root `parent-task` node is never modified.

### Step 3: Display

Tree is a Mermaid graph. Display to user as ASCII using box-drawing characters. Represent state using emoji.

Show project title in bold.
Then show legend line above the tree:

`Legend: 🟡 To do  🔶 In progress  ✅ Completed  🔴 Blocked  🟣 Punt  🔵 Notes`

Then show tree, with no emoji for parent task.

### Step 4: Review

Ask user to review current tree. Any new stories to add?

### Step 5: Find Next Task

Find next `todo` story to work on. Ask user to confirm.

Keep stories ordered left-to-right in diagram.

### Step 6: Sync Names

Keep node names and user story labels in sync.

### Step 7: Mark as In-Progress

Mark chosen story as `in-progress`. Change all parent nodes to `in-progress` as well, except root `parent-task`.

### Step 8: Complete

When task is done:
- Mark it as `complete`
- Ask user: "Any new stories to add next to this one?"
- If not, go up one level in tree
- Loop back to Step 4

## Optional Features

### Side Notes

A side note is a free-floating box not connected to tree. Use it for reminders, open questions, or context that isn't a task. Only add when user requests one.

Trigger phrases (examples):
- "Add note to discovery tree"
- "Add side note to discovery tree"

To list existing side notes (read-only), trigger phrases:
- "What notes are on the tree?"
- "List the side notes"

Read each `notes`-classed node and report its id and label. Do not modify the file.

If trigger phrase does not include note text (e.g. user just says "add a side note" with no content), prompt user: "What should the side note say?" Do not invent content or use a placeholder. Wait for user's response before adding node.

To add a side note:
- Declare a node with a unique id, e.g. `note-1["Check API rate limits"]`
- Apply `notes` class: `class note-1 notes`
- Optionally anchor it near another node with an invisible link: `parent-node ~~~ note-1` (no visible edge is drawn)
- Place side notes after legend block and before `classDef` block

#### Layout: choose by note count

- **1 note:** declare it loose and anchor near a node: `parent-node ~~~ note-1`. No subgraph.
- **2–5 notes:** wrap them in a single invisible row subgraph (see below).
- **6+ notes:** use multiple row subgraphs, max 5 per row.

Do not mix loose anchored notes with row subgraphs — the competing invisible links fight Mermaid's layout. Once a second note is added, move the first into a row subgraph.

#### Layout: max 5 per row

Limit each row of side notes to 5; stack additional notes in new rows below.

- Group every 5 notes into an invisible subgraph with `direction LR` and a blank label, e.g. `subgraph note-row-1[" "]`
- Chain notes inside a row with invisible links: `note-1 ~~~ note-2 ~~~ note-3 ~~~ note-4 ~~~ note-5`
- Chain rows top-to-bottom with invisible links: `note-row-1 ~~~ note-row-2`
- Hide each row's border: `style note-row-1 fill:none,stroke:none`
- Always close each subgraph with `end`

Example (6 notes → row of 5, then row of 1):

```
subgraph note-row-1[" "]
    direction LR
    note-1 ~~~ note-2 ~~~ note-3 ~~~ note-4 ~~~ note-5
end
subgraph note-row-2[" "]
    direction LR
    note-6
end
note-row-1 ~~~ note-row-2
style note-row-1 fill:none,stroke:none
style note-row-2 fill:none,stroke:none
```

#### Editing and Removing Side Notes

To **edit** a note, change only the label text in its node declaration (e.g. `note-1["New text"]`). Leave id and `class` line unchanged.

To **remove** a note:
- Delete its node declaration and its `class note-N notes` line.
- Splice it out of `~~~` chain so remaining notes stay linked (e.g. removing `note-3` from `note-2 ~~~ note-3 ~~~ note-4` leaves `note-2 ~~~ note-4`).
- Never renumber or reuse ids — leave gaps. Renumbering churns diff for no benefit.
- Re-balance rows so no row exceeds 5 and no row is empty: pull first note of each later row up to fill gap, then drop layout down a tier if total now fits (6+ → 2–5 → 1) per count rules above. Delete any subgraph left empty and its `style`/chaining lines.