reading-tree

Reading Tree

Use this skill when the user wants to transform an article or chapter into a linked reading interface:

• The tree must preserve the source order.
• Clicking a node must jump to and highlight the covered source paragraphs.
• Clicking a source paragraph must jump back to the best matching node.
• The result must stay suitable for full reading, not just skimming.

Outcome

Produce a workspace that can build:

• site/data/source.js
• site/data/tree-data.js
• a static interactive site in site/

The generated site includes:

• bidirectional node/paragraph linking for reading
• global search where text and outline labels use JavaScript regex, while roles stay plain
• AND as the default search operator, with explicit uppercase OR
• optional field prefixes such as role:example

Shared tooling lives in scripts/. For online tools such as ChatGPT or Claude.ai that cannot serve the generated UI directly, provide a .zip archive of the full site/ folder and tell the user to extract it and open site/index.html in a browser. Do not hand off only index.html, because it depends on sibling assets. The default site template opens locally, but it is not fully self-contained in the strict offline/privacy sense: when online, it requests Google Fonts for typography. If those requests are blocked, the browser falls back to local serif fonts and the UI still works.

The reusable workspace scaffold lives in assets/workspace-template/.

Workflow

1. Copy assets/workspace-template/ into a fresh workspace.
2. Save the source text as article.txt, preserving the original paragraph boundaries by default. Prefer one source paragraph per line. Only split one original paragraph into multiple lines when it is very long or contains an obvious internal semantic shift.
3. Inspect article.txt with real line numbers from the terminal, for example nl -ba article.txt.
4. For long files, inspect windows such as sed -n '120,180p' article.txt | nl -ba -v120 instead of counting lines in model context.
5. Create splits.json with semantic paragraph start lines only. If article.txt already uses one source paragraph per line, the split list will often start on every non-empty line.
6. Run python3 reading-tree/scripts/build.py <workspace> --step source and inspect site/data/source.js.
7. Create tree.json after the paragraph split is stable. Every node must declare at least one non-empty broad role via roles.
8. Run a structure audit against references/authoring.md, especially Breadth Control and Final Structure Check.
9. Materialize that review as a markdown table before continuing. Use one row per non-leaf sibling group in tree order so grouping choices are explicit. Top-level nodes are mandatory rows.
10. Regroup until the structure audit table is clean. 6 is a ceiling, not a target for normal-length texts. For substantially longer texts, treat the breadth numbers as defaults rather than hard caps, but justify any exception in the audit table.
11. Prefer adding intermediate grouping nodes over coarsening paragraph splits when reducing breadth.
12. During structural iteration, run python3 reading-tree/scripts/validate.py <workspace> after each structural edit as cheap feedback.
13. Run a mandatory final label lint pass against references/authoring.md, especially the Meaning Fidelity Check and Final Label Check sections. Inspect every node label one by one in tree order.
14. Materialize that review as a markdown table before continuing. Use one row per label, and include both style columns and meaning-fidelity columns from references/authoring.md, plus the roles columns for every row. Treat the table as the required reasoning scaffold, not as optional presentation.
15. Rewrite every weak or semantically overstated label before continuing. Update the table until every row passes. Do not continue if even one row still fails.
16. After the structure audit table and label audit table are both clean, run python3 reading-tree/scripts/validate.py <workspace> again as the required final validation pass.
17. Run python3 reading-tree/scripts/build.py <workspace> --step all.
18. To inspect or hand off the result, note that site/index.html can be opened directly in a browser, or cd site/ and serve it with python3 -m http.server 8000 --bind 127.0.0.1. For online tools such as ChatGPT or Claude.ai that cannot serve the UI themselves, provide a .zip archive of the full site/ folder and instruct the user to extract it and open site/index.html. Do not provide only index.html. Also mention that the default template requests Google Fonts when online; if those requests are blocked, the browser falls back to local serif fonts.
19. If serving locally, tell the user to open http://127.0.0.1:8000/ in a browser. Only launch a browser from the agent if the user explicitly asks for that.