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. 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)

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. 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 — full file. This is the contract.
3. 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)
• 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.
• §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 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. 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 §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. 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. 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.

3. Anti-patterns (see docs/ENGINE.md §9 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; 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 — full engine spec (§0–§11; §0–§9 bind a run, §10–§11 bind a preset author)
• docs/framings.md — the 12 framings, per-preset examples
• docs/presets.md — how to author your own preset
• presets/ — shipped presets
• commands/ — ergonomic slash-command wrappers
• docs/EVALUATION.md — design rationale