docs(uipath-maestro-flow): add table of contents to two large shared docs#799
docs(uipath-maestro-flow): add table of contents to two large shared docs#799uisherif wants to merge 1 commit into
Conversation
…docs Add a top-of-file ToC to variables-and-expressions.md (685 lines, 12 H2 sections) and file-format.md (493 lines, 13 H2 sections) so agents and humans can jump to a specific section instead of reading the whole file. Pure addition — no existing content modified.
|
Claude finished @uisherif's task in 2m 3s —— View job PR Review: docs(uipath-maestro-flow) — Table of Contents for Shared Docs
SummaryAdds a Change-by-Change Review1.
|
| Area | Status | Notes |
|---|---|---|
| Frontmatter | N/A | No frontmatter changes |
| E2E Tests | N/A | Documentation-only change, no behavior change |
| Skill Body | N/A | SKILL.md not modified |
| References & Assets | OK | ToC blocks correctly placed, all anchors verified |
| Repo Hygiene | OK | No cross-skill refs, no secrets, scoped to target files only |
Issues for Manual Review
None found.
Conclusion
Clean, low-risk, purely additive change. All 25 ToC anchor links resolve correctly against their target H2 headings. The ToC placement in both files is sensible — after introductory context, before the first content section. No issues found. Approve.
The problem
Two shared docs in
uipath-maestro-flow/references/shared/are reached by nearly every agent task and read whole because neither has a table of contents:variables-and-expressions.md— 685 lines.file-format.md— 493 lines.Both have well-structured H2 sections (12 and 13 respectively), but the agent has no way to jump to the one it needs — e.g. "JSON shape of the
outputsblock", "what--inputsJSON looks like forflow debug", "how subflows scope variables". The skill router inSKILL.mdalready references these docs for narrow needs, but the agent loads them in full.In the two hot-path traces from the earlier review:
variables-and-expressions.mdalone added 685 lines to the cumulative read.variables-and-expressions.md(685) +file-format.md(493) added 1,178 lines.Why this fix
A 10–15 line ToC at the top of each file lets an agent (or human) jump straight to the relevant section. Zero content change, no risk to any existing rule or guidance — pure progressive disclosure.
What changes
variables-and-expressions.md: insert a## Table of contentsblock after the introductory blockquote (line 17), listing the 12 H2 sections with anchor links.file-format.md: insert a## Table of contentsblock after the introductory paragraph (line 4), listing the 13 H2 sections with anchor links.Expected impact
Once the ToC exists, an agent can read the file's intro + ToC (~25 lines) and jump to one or two relevant H2 sections (~50–100 lines each) instead of reading the whole 493- or 685-line file. Estimated savings on a typical task that touches these docs: 300–500 lines of avoided read each time the file is consulted.
No measurable downside — both files still load in full when an agent decides to read top-to-bottom; the ToC just makes targeted access possible.
Validation
.maintenance/check-anchors.sh: all 25 new ToC anchor links resolve. The 3 pre-existing bad anchors onmain(inediting-operations-json.mdandevaluate/CAPABILITY.md) are unchanged..maintenance/check-links.sh: no new failures.Out of scope
Same out-of-scope list as #798. ToCs on smaller reference files (planning-arch, editing-operations-json, connector/impl, etc.) deferred — they're under or near the 500-line threshold and the value of a ToC on them is lower.