stair-toc

Grounds retrieval in document table-of-contents hierarchy instead of length-based chunking.

1|Updated Aug 27, 2025
One-click install
npx skills add https://github.com/IgorGanapolsky/Random-Timer --skill stair-toc-igorganapolsky
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: stair-toc
Source: https://github.com/IgorGanapolsky/Random-Timer/tree/main/.claude/skills/stair-toc
Command: npx skills add https://github.com/IgorGanapolsky/Random-Timer --skill stair-toc-igorganapolsky

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Length-based chunking in RAG pipelines discards the hierarchy that a document's table of contents already encodes, causing retrieval to lose structural context and enabling hallucinated citations. This Skill applies the IBM STAIR approach of grounding the retrieval address space in ToC paths so claims cite real heading locations. ## Core Features & Use Cases - ToC-based retrieval: Retrieve content by heading path (path#slug) rather than flat 512-token chunks, preserving document hierarchy. - Grounding evaluation: Run evaluate_grounding against heading paths and evaluate_chunking in toc mode to verify retrieval quality before claiming a result is grounded. - Fail-closed validation: The stair_toc.py script returns JSON with ok flags and exits 0 only when every check passes, blocking ungrounded claims. - Use Case: When a user asks whether "the docs say" something about live evidence or WQTU, run the script with --mode toc and a --cite path#slug argument to confirm the citation resolves to a real heading before answering. ## Quick Start Ask the assistant to verify a retrieval claim against a markdown document's table of contents by running the stair_toc script in toc mode with a query and a heading citation.

Frequently Asked Questions about stair-toc

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I ground RAG retrieval in a table of contents?

Run the stair_toc.py script with --mode toc, passing the markdown source file, a query, and a --cite argument in path#slug form. Retrieval is considered grounded only when every JSON ok flag is true and the process exits 0.

What is the STAIR approach to retrieval?

STAIR is an IBM method where the retrieval address space is grounded in a document's table of contents rather than length-based chunks. This preserves hierarchy so claims cite real heading paths instead of arbitrary token windows.

Does this require paid embedding APIs or fine-tuning?

No. The Skill explicitly forbids paid embedding APIs and fine-tuning DSI or STAIR models. It relies on the existing ToC structure of markdown documents and ranking by IAP or WQTU rather than token embeddings.

When should I not use ToC-based retrieval?

Avoid it when documents lack a meaningful heading hierarchy, since the method depends on a table of contents to define the address space. Also do not use it to rewrite ROSE-lite WIP work, which is explicitly out of scope.

Why does length-based chunking cause hallucinated citations?

Splitting documents by fixed token length discards the heading hierarchy, so retrieved fragments lose their structural address. Generative retrieval over such chunks can produce citations that do not correspond to any real section.