# tree

Adopt this skill: https://proskills.md/skills/other/skymanbp-cc-tree-skills-tree

Page: https://proskills.md/skills/other/skymanbp-cc-tree-skills-tree
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/tree/SKILL.md
size: 15267
sha: 1bb0f8e46385423251edd19a1b69127a34a46fc0
upstream: https://github.com/skymanbp/cc-tree/blob/main/skills/tree/SKILL.md

````text
---
name: tree
description: Universal radial-tree exploration engine — loads a preset, grounds a root, expands every node through 12 framing passes, derives each child in 12 evidence-bearing fields, scores it, and recurses on `advances` leaves until substantive convergence (or a user cap). Caps default to ∞; `defer / TODO / NEEDS-MORE-INFO` leaves are hard-banned. Use when the user wants the engine itself — a custom preset via `--preset <path>`, explicit control of a run, or "tree of thoughts" / 穷尽的树状探索 in general; for the four shipped use-cases prefer `/cc-tree:brainstorm`, `/cc-tree:attack`, `/cc-tree:design`, `/cc-tree:code-audit`, whose descriptions carry the per-use-case triggers.
disable-model-invocation: false
argument-hint: "<root> --preset <name|path> [--lang <tag|auto>] [--width N|∞] [--depth N|∞] [--rounds N|conv] [--max-branches N|∞] [--out <dir>] [--glossary <path>] [--field <name|path>] [--seed-from <primary.md>] [--no-grill] [--no-online] [--min-frameworks N] [--min-novelty-ratio R]"
---

# tree — universal radial-tree exploration engine

> **What this skill is.** A single engine implementing recursive
> radial-tree exploration (root → 12-framing expansion → per-node
> 12-field derivation → score → recurse on high-verdict leaves →
> terminate on **substantive convergence**). What varies between
> use-cases (brainstorm vs critique vs design vs code-audit) is the
> baseline recipe, node schema, scoring dimensions, and verdict
> vocabulary — all parameterized via a **preset** file.

> **What this skill is NOT.** Not a one-shot LLM call that returns a
> bulleted list. Not a chat interface — once the §2.0 glossary grill
> has settled terminology and the root is written, the engine runs to
> convergence without further prompts (§F6).
> Not bundled with a model — pure prompt-engineering on top of Claude
> Code's existing model setting.

The full engine specification lives in [`docs/ENGINE.md`](../../docs/ENGINE.md).
This SKILL.md is a 7-step navigation guide; **Read `docs/ENGINE.md`
before producing the first node** (the engine spec is what defines
"valid" for everything you'll write).

---

## 1. Invocation

```
/cc-tree:tree <root> --preset <name|path> [flags]
```

**`<root>`** is preset-typed:
- `brainstorm` preset → topic string, e.g. `"ways to detect dark-matter substructure"`
- `attack` preset → file path (`.md` / `.tex` / etc.) or quoted argument-text
- `design` preset → design-prompt string or `.md` file path
- `code-audit` preset → file path or directory path

**`--preset`** is required:
- Built-in: `brainstorm`, `attack`, `design`, `code-audit` (resolve to
  `presets/<name>.md` in this plugin)
- Path: `./my-custom.md` (any .md file with the right frontmatter)

### Common flags (apply across presets)

| Flag | Default | Meaning |
|---|---|---|
| `--lang <tag\|auto>` | **en** | Output language for all localized prose (node statements, derivations, report narrative, warnings). Machine tokens — flag/command names, frontmatter & JSON keys, `root_kind` values, verdict labels, status tokens, filenames — always stay English. `<tag>` is a BCP-47-like code (`en`, `zh`, `zh-Hans`, `zh-Hant`, `fr-CA`); `zh` = Simplified Chinese, `zh-Hant` = Traditional. `auto` detects the dominant language of `<root>` and falls back to `en` for mixed / path-only / code-only input. Resolved **once before preset load**, recorded in run metadata (`language_request` / `output_language` / `language_source`), and never prompted mid-run. Full precedence, resume, and chain semantics: [`docs/ENGINE.md §1.0`](../../docs/ENGINE.md#10-output-language-resolution-and-schema-boundary). |
| `--width N` | **∞** | Cap on final leaf count (the outer arc of the tree). `∞` / `inf` / unspecified all mean unlimited. |
| `--depth N` | **∞** | Cap on tree depth from root. |
| `--rounds N` | `conv` | Cap on expansion rounds. `conv` = no cap; terminate by §6 substantive convergence. |
| `--max-branches N` | **∞** | Cap on new branches per node per round. **Floor is 12** because §3 requires all 12 framings to fire; this flag only raises the ceiling. |
| `--out <dir>` | `tree-out/<UTCdate>__<slug>/` | Output directory. Per-preset commands override (e.g. `brainstorm-out/`). |
| `--glossary <path>` | (preset-determined) | Path to a glossary / FACTS.md / glossary section in a dossier; used by §2.0 grill prelude. |
| `--field <name\|path>` | (none) | Field profile for domain-aware reviewer weighting. `<name>` → `field-profiles/<name>.md` in this plugin; `<path>` → a literal file. Feeds §3.C / §3.D / §3.I / §3.J + the §3.X / §4 evidence bar. Missing profile → warn + continue (non-blocking). See [`docs/ENGINE.md` §2.2](../../docs/ENGINE.md#22-field-profile-optional---field-namepath). |
| `--seed-from <primary.md>` | (none) | Seed the tree from a prior run's primary deliverable (`shortlist.md` / `options.md` / `confirmed.md`): each listed item enters as a depth-1 seed node and is re-expanded. The substrate for cross-preset chaining ([`docs/chaining.md`](../../docs/chaining.md)). Alias: `--from-prior`. |
| `--no-grill` | off | Skip §2.0 glossary grill prelude. Marks root-node terms as `unverified`; §6 convergence adds a warning. |
| `--no-online` | off | Disable `WebSearch` / `WebFetch`. Local + already-Read references only. |
| `--min-frameworks N` | 12 | Minimum framing passes per node. **Floor is 12** (full §3.A–§3.L); flag exists for documentation, not relaxation. |
| `--min-novelty-ratio R` | 0.15 | §6.1 condition 2 requires "last 2 rounds' high-verdict / total < R". |

> Presets and their command wrappers may document additional
> preset-specific flags (e.g. `attack`'s
> `--focus <section|claim|equation>`); a flag documented by the active
> preset or its wrapper is not "unknown" (`docs/ENGINE.md` §1.3).

> Caps default to ∞ on purpose. The intended termination is §6
> substantive convergence — see [`docs/ENGINE.md §6`](../../docs/ENGINE.md#6-6-convergence).
> Caps are escape valves for quick exploration; when one trips, the
> engine still drives every in-flight node to a complete state before
> reporting `WIDTH_CAP_REACHED` / `DEPTH_CAP_REACHED` /
> `ROUNDS_EXHAUSTED`.

---

## 2. Execution flow

> **Required Reads at session start** (before producing the first node):
> 1. The preset file (`presets/<name>.md` or `--preset <path>`) — full file.
> 2. [`docs/ENGINE.md`](../../docs/ENGINE.md) — full file. This is the contract.
> 3. [`docs/framings.md`](../../docs/framings.md) — the 12 framings with per-preset
>    examples.
> 4. If `--glossary <path>`: Read that glossary file in full.

### Step 1 — Preset load

Open the preset file. Extract from its YAML frontmatter:
- `name`, `description`, `use-when` (informational)
- `root_kind` — `topic | artifact | code | design-prompt`
- `subject_label` — what each tree node is called (`idea`, `critique`,
  `option`, `finding`, …)
- `verdict_enum` — 4-tuple: `advances / kept / pruned / blocked`
- `convergence_metric` — which verdict *role* counts toward the §6.1
  condition-2 ratio.
  It must be one of the four `verdict_enum` role keys verbatim
  (`advances` / `kept` / `pruned` / `blocked`); alias spellings like
  `novelty_ratio` are rejected by the validator. All four shipped
  presets use `advances` ([`docs/presets.md`](../../docs/presets.md))
- `score_dims` — list of 5 scoring dimensions (key + name + desc)
- `node_schema` — list of 12 node-field names
- `output_artifacts` — file names for the per-verdict final reports

The preset body (below frontmatter) supplies:
- §2 baseline recipe (what to Read / Grep / WebFetch to build the root)
- Optional per-framing examples (§3.A–§3.L flavored for this preset)
- Optional anti-pattern list specific to this preset

### Step 2 — §2 baseline

Follow the preset's baseline recipe. For all presets this includes:
- §2.0 (unless `--no-grill`): glossary-grill prelude. Lock root-node
  noun-phrases to the glossary if one was supplied; surface MISSING /
  AMBIGUOUS / CONFLICT one question at a time per
  [`docs/ENGINE.md §2.0`](../../docs/ENGINE.md#20-glossary-grill-prelude-mandatory-unless---no-grill).
- §2.A or §2.B (preset-determined): build the root node from real
  evidence (Read files, Grep symbols, WebFetch references). The root
  must have the 5-8 fields the preset specifies, each with `file:line`
  or URL evidence.

Save the root to `<out>/tree.md` + `<out>/tree.json` before producing
any framing branches.

### Step 3 — §3 framing pass (12 passes per node)

For each node (starting with root, then any high-verdict leaf in the
next round):

Run §3.A through §3.L, each producing **at least 1** new child branch.
See [`docs/framings.md`](../../docs/framings.md) for the full prompt per
framing, including domain-specific examples per preset.

**Parallelize when fan-out ≥ 5** (always true for the root and hot
leaves): dispatch the 12 framings across `Agent(Explore)` sub-agents per
the mandatory protocol in
[`docs/ENGINE.md` §8.1](../../docs/ENGINE.md#81-sub-agent-dispatch-mandatory-when-a-nodes-expected-fan-out--5).
Running them sequentially at that fan-out is a defect. Deep marginal
leaves (< 5 expected children) may run sequentially.

§3.X (if `--no-online` is off): per node, do 1 round of `WebSearch` +
`WebFetch`. **The query set is preset-determined** (brainstorm/design →
prior art + tooling; attack → critiques / errata; code-audit → CVEs /
advisories) — see [`docs/framings.md`](../../docs/framings.md) §3.X.

### Step 4 — §4 per-branch 12-field derivation

For each branch produced in §3, fill the preset's 12 node-field schema.
Field requirements live in
[`docs/ENGINE.md §4`](../../docs/ENGINE.md#4-4-per-node-derivation-12-field-schema).
Hard rules:
- No field may contain `应该 / 大概 / probably / maybe / 也许` — the
  field is invalid and must be rewritten.
- No field may contain `defer / future work / TODO / FIXME / 略 /
  details omitted / 待定 / NEEDS-MORE-INFO`-style placeholders — the
  node is forced to `INCOMPLETE_FORBIDDEN` and **must** be driven to
  completion before counting.
- Numerical claims require a one-shot `python (sympy/numpy)` sanity
  check via `Bash` — output pasted into the field.
- External references require `WebFetch` of the actual arXiv abs / DOI
  / spec page; `WebSearch` snippets are not sufficient.

Append the filled node to `tree.md` + `tree.json` immediately
(incremental write — see §7 for crash-safety contract).

### Step 5 — §5 scoring and verdict

Score the node along the preset's 5 dimensions (each 0–3, integer).
Sum = `score` (max 15). Map score → verdict via the preset's
`verdict_enum` and the preset-specific rule (e.g. brainstorm:
`score ≥ 11 ∧ no [NEEDS_VERIFICATION] → PROMISING`; attack:
`score ≥ 11 ∧ artifact_defense empty → CONFIRMED`).

Sibling merging (§5.4): any two siblings with cosine similarity ≥ 0.85
on their idea / critique / option / finding statement → merge, keep
the higher-scored one, tag the other `MERGED_INTO=<id>`.

### Step 6 — §6 convergence check

After every round, evaluate the 6 conditions in
[`docs/ENGINE.md §6`](../../docs/ENGINE.md#6-6-convergence).
All 6 must hold simultaneously to declare `CONVERGED`. If any
user-specified `--width / --depth / --rounds` cap trips first, report
the appropriate `*_CAP_REACHED` / `ROUNDS_EXHAUSTED` status, but **all
leaves must be complete** before stopping.

If neither convergence nor a cap-trip, pick the highest-verdict leaf
that hasn't been re-expanded yet, run §3–§5 on it, and loop.

### Step 7 — §7 final report

When termination is declared, write the preset's `output_artifacts` to
`<out>/`. For all presets this includes:
- `tree.md` — full tree, human-readable
- `tree.json` — full tree, machine-readable
- The preset-specific primary deliverable (`shortlist.md`,
  `confirmed.md`, `options.md`, `findings.md`)
- The preset-specific secondary deliverables (`pending.md`,
  `marginal.md`, `refuted.md`, …)

Then emit a terminal-report block per
[`docs/ENGINE.md#74-final-report`](../../docs/ENGINE.md#74-final-report).

---

## 3. Anti-patterns (see [`docs/ENGINE.md §9`](../../docs/ENGINE.md#9-anti-patterns-full-list) for the full list)

The five that most reliably degrade output quality:

1. ❌ **Pseudo-divergence.** Two branches that differ only in word
   choice. Each branch must offer at least one of (a) a different
   testable prediction, (b) a different failure mode, (c) a different
   resource profile. Otherwise: merge.

2. ❌ **Defer-as-output.** "This direction is promising but requires
   detailed analysis beyond scope." Forbidden by §F8. The engine must
   actually do the analysis (Read / WebFetch / Bash) or route to a
   sibling via §3.E constraint-variation.

3. ❌ **Cap-as-convergence.** Declaring `--width 20` reached → done.
   §6 convergence is the *intended* termination; caps are escape
   valves and trip ≠ converge.

4. ❌ **Skipping §3.K.** "High-risk branches feel speculative, I'll
   focus on safe ones." §F4 + §3.K force ≥ 1 fully-explored
   high-risk branch per pass; absent it the pass is invalid.

5. ❌ **WebSearch snippet → conclusion.** Snippets are search results,
   not source-of-truth. Every external citation requires `WebFetch`
   of the actual page; otherwise the field is invalid (rule 04 +
   rule 01 from cc-enforcer, if installed).

---

## 4. Output contract

```
<out>/
├── tree.md             # human-readable outline of every node
├── tree.json           # machine-readable, full 12 fields per node
├── glossary-anchors.md # §2.0 prelude output (unless --no-grill was set)
├── <primary>.md        # preset's "advances" / top-recommendation file
├── <secondary>.md*     # preset's "marginal / pending / refuted" files
├── <per-item>.md*      # preset-specific per-item detail files, when the
│                       #   preset's body declares them (design writes
│                       #   option_<id>.md, the design→attack chain handoff)
├── REPORT.md           # §7.4 final-report block (also echoed to stdout)
└── nodes/
    └── <id>.md         # spilled when a node's evidence > 100 lines
```

This is the same layout as [`docs/ENGINE.md` §7.2](../../docs/ENGINE.md#72-output-directory-layout);
that section is authoritative if the two ever disagree.

Each node lands the moment its 12 fields are filled (§7.1 incremental
write contract). Restart from interruption: just re-invoke the same
`/cc-tree:tree <root> --preset <name> --out <same-dir>` — the engine
detects the existing tree and resumes from the highest-id leaf.

---

## 5. References

- [`docs/ENGINE.md`](../../docs/ENGINE.md) — full engine spec (§0–§11;
  §0–§9 bind a run, §10–§11 bind a preset author)
- [`docs/framings.md`](../../docs/framings.md) — the 12 framings, per-preset examples
- [`docs/presets.md`](../../docs/presets.md) — how to author your own preset
- [`presets/`](../../presets/) — shipped presets
- [`commands/`](../../commands/) — ergonomic slash-command wrappers
- [`docs/EVALUATION.md`](../../docs/EVALUATION.md) — design rationale
````

## File: README.md
upstream: https://github.com/skymanbp/cc-tree/blob/main/README.md

````text
# cc-tree

[![CI](https://github.com/skymanbp/cc-tree/actions/workflows/ci.yml/badge.svg)](https://github.com/skymanbp/cc-tree/actions/workflows/ci.yml)
[![Latest release](https://img.shields.io/github/v/release/skymanbp/cc-tree?color=6aa84f&label=release)](https://github.com/skymanbp/cc-tree/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-8e7cc3)
[![Star on GitHub](https://img.shields.io/github/stars/skymanbp/cc-tree?style=social)](https://github.com/skymanbp/cc-tree/stargazers)

> Language: English (canonical). Chinese: [`README.zh.md`](README.zh.md).

**cc-tree makes Claude Code think in a tree you can audit: every node cites evidence, and the run stops when it converges.**
One exploration engine, four presets — brainstorm, adversarial critique, design-space exploration,
code audit. Every node is fully derived with `file:line` or URL evidence, deferred leaves
(`defer / future-work / TODO / NEEDS-MORE-INFO`) are banned, and a run stops on substantive
convergence rather than on a node budget.

```bash
claude plugin marketplace add skymanbp/cc-tree
claude plugin install cc-tree@cc-tree
```

## 1 · The problem, and what cc-tree does about it

### 1.1 The problem it targets

Ask an LLM to *brainstorm*, *review this critically*, *compare these designs* or *audit this file*,
and the same five failure modes come back:

| Failure mode | What it looks like |
|---|---|
| **Shallow coverage** | the three most obvious angles, then a summary |
| **Deferred leaves** | "promising, needs a deeper survey — future work" |
| **Pseudo-divergence** | six branches that are one branch with the nouns swapped |
| **Convenient convergence** | "that about covers it", just as new ideas get expensive |
| **Unverifiable output** | a chat log: nothing cites a line, nothing survives the scroll-back |

cc-tree inverts each row: fixed-breadth coverage, no deferrals, merged duplicates, a convergence
test you can check, and a `file:line` or URL behind every claim.

### 1.2 What it does — five capabilities

| # | Capability | Invoke | Deliverable |
|---|---|---|---|
| **1** | **Divergent exploration** — research directions or solution paths, grown until no new high-value branch appears | `/cc-tree:brainstorm` | `shortlist.md` |
| **2** | **Adversarial critique** of a document, argument or proposal; every leaf is `CONFIRMED` / `MARGINAL` / `REFUTED`, with the defense the artifact already mounts | `/cc-tree:attack` | `confirmed.md` |
| **3** | **Design-space exploration** — options × trade-offs × reversibility × cost, ending in a `RECOMMENDED` short-list | `/cc-tree:design` | `options.md` |
| **4** | **Code audit** — threat-model, contract and cross-file bugs a linter cannot see, each with `file:line` and a fix | `/cc-tree:code-audit` | `findings.md` |
| **5** | **Chaining** — brainstorm → design → attack, top-K piped between stages | `/cc-tree:tree-chain` | per stage + handoff log |

All five are the same engine; a preset changes the vocabulary, never the loop
([`docs/ENGINE.md`](docs/ENGINE.md) §10).

### 1.3 Working scope — what cc-tree is not

- **Not a one-shot tool or a chat.** A run is recursive and takes minutes to hours; after the §2.0
  glossary grill it runs to convergence without asking (§F6). You steer with flags.
- **Not a substitute for a domain expert, and not bundled with a model.** It is prompt engineering
  on your Claude Code model setting; a human decides which leaves to act on.
- **Not a linter.** `code-audit` targets what static analysis structurally cannot.

## 2 · How it works

### 2.1 The shape — one root, growing outward

A run is a tree grown outward from one root — your input. Every expansion tries all 12 framings,
so a node that grows gets one child per framing; each child is derived and scored, and only
`advances` children are expanded again, so branches stop at different depths. The run ends on §6
convergence.

![One converged cc-tree run drawn as a radial tree: the root at the centre, depth as rings. The
root's twelve children are lettered A–L, one per framing; A and D advanced and grew twelve
children each, one of A's children grew again to depth 3, and every other node is a tip carrying
its verdict — advances, kept or pruned. The run has n = 49 nodes and width = 45 tips. A table maps
the four roles onto each preset's verdict words.](docs/assets/cc-tree-radial-tree.svg)

<sub><strong>root</strong> is the input; a <strong>node</strong> is one idea, critique, option or
finding; <strong>depth</strong> is the ring a node sits on; <strong>width</strong> counts the
terminal tips, never a <code>blocked</code> one (§0.1); <strong>n</strong> counts every node. The
picture is one run of one preset — the four presets differ only in the verdict words of the table
beneath the tree (§5.2). Source:
<a href="tools/gen_radial_tree.py"><code>tools/gen_radial_tree.py</code></a>, which refuses to
draw a tree the engine could not produce.</sub>

### 2.2 The five irreducible steps

All five are specified in [`docs/ENGINE.md`](docs/ENGINE.md) and binding on every preset.

```mermaid
flowchart LR
    R([root<br/>topic · artifact · code · design]) --> F{{12 framing passes<br/>§3.A–§3.L}}
    F --> D[per-node 12-field derivation<br/>evidence · no hedging · no defer]
    D --> S[score 5 dims → verdict]
    S -->|advances| RE((re-expand<br/>this leaf))
    RE --> F
    S -->|kept / pruned| K[keep in tree,<br/>don't re-expand]
    S -->|blocked| B[INCOMPLETE_FORBIDDEN<br/>drive to completion]
    B --> D
    S --> C{§6 convergence?<br/>6 conditions all true}
    C -->|no| RE
    C -->|yes| OUT[/final report +<br/>tree.md · tree.json/]
```

1. **Ground the root (§2).** The preset's recipe builds it, every field cited; an optional glossary
   grill (§2.0) pins your project's terms first.
2. **Expand through 12 framings (§3).** First-principles, inversion, cross-disciplinary, red team,
   constraint variation, scale, substitution, office-hours 6Q, contrarian, failure-driven,
   high-risk asymmetric, and a meta self-audit — fixed, so the uncomfortable angles cannot be
   skipped. A §3.X web cross-check runs per node unless `--no-online`. Prompts:
   [`docs/framings.md`](docs/framings.md).
3. **Derive every child in 12 fields (§4).** A blank, hedged or deferred field makes the node
   `INCOMPLETE_FORBIDDEN`, which blocks termination until it is completed.
4. **Score and decide (§5).** Five dimensions, 0–3 each: `≥ 11` → `advances` (re-expanded),
   `8–10` → `kept`, `≤ 7` → `pruned`, unverified → `blocked`. Siblings at cosine ≥ 0.85 merge.
5. **Stop only on convergence (§6).** Six conditions at once: nothing incomplete, the `advances`
   ratio below `--min-novelty-ratio`, all 12 framings fired, every `advances` leaf re-expanded to
   exhaustion, a §3.K high-risk branch present, no cap tripped. A tripped cap is reported as
   `WIDTH_CAP_REACHED` / `DEPTH_CAP_REACHED` / `ROUNDS_EXHAUSTED`, never as `CONVERGED`.

### 2.3 The eight quality gates

Violating any of these invalidates the round (§0.5); each kills a failure mode from §1.1.

| Gate | Bans | Kills |
|---|---|---|
| §F1 | memory-cited claims — verify in the same turn | unverifiable output |
| §F2 | synonym-swapped siblings — merged | pseudo-divergence |
| §F3 | "obvious" / "details omitted" derivations | shallow coverage |
| §F4 | a framing pass without one fully derived high-risk branch | shallow coverage |
| §F5 | "out of ideas" passed off as convergence | convenient convergence |
| §F6 | mid-run prompting | convenient convergence |
| §F7 | the engine narrowing its own caps | convenient convergence |
| §F8 | `defer / future work / TODO / 待定 / NEEDS-MORE-INFO` leaves | deferred leaves |

Why one engine with presets rather than four skills, why 12 framings, and how this differs from
academic Tree-of-Thoughts: [`docs/EVALUATION.md`](docs/EVALUATION.md).

## 3 · What a run actually produces

From this repository's showcase
````
