headwater-orient

Locate relevant documents in a typed documentation corpus using graph-based routing commands.

Updated Aug 8, 2026
One-click install
npx skills add https://github.com/headwater-ai/headwater --skill headwater-orient-headwater-ai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: headwater-orient
Source: https://github.com/headwater-ai/headwater/tree/main/.claude/skills/headwater-orient
Command: npx skills add https://github.com/headwater-ai/headwater --skill headwater-orient-headwater-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Finding what a large documentation corpus already says about a subject usually means searching across directories or reading specification parts end to end. This Skill uses the graph the headwater engine already built to answer "where does this subject live" with a single command, before any document is opened. ## Core Features & Use Cases - Task routing: headwater route matches a task description against declared document purposes, returning the documents that answer it and reporting honestly when nothing matches. - Document explanation: headwater explain prints a document's kind, purpose, summary, warrant, facets, and every relation edge in and out, so a wrong guess still names the right document. - Corpus checking: headwater check reports what is currently wrong with the corpus when a task is to fix an unnamed defect. - Use Case: At the start of a session about a decision or obligation in this repository, run headwater route with the task in the words it was asked, then headwater explain on the result to see its summary and citing documents before opening anything. ## Quick Start Ask the assistant to run headwater route with your task description against the repository root to find which documents already cover the subject.

Frequently Asked Questions about headwater-orient

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

FAQPage Schema
How do I find what a documentation corpus says about a subject?

Run headwater route with the task phrased in the words it was asked, against the corpus root. It matches declared document purposes rather than text, so it is right about subject and indifferent to vocabulary, and it reports honestly when nothing matched.

What does headwater explain show about a document?

headwater explain prints the document's kind, shelf, purpose, summary, warrant, required facets, allowed relations, and every edge in and out with the summary of the document at the other end. The summary and edges let you reach the right document without reading the wrong one.

When should I use grep instead of headwater route?

A text search is right for literal strings: spellings, identifiers, error message phrases, or terms whose home you are trying to find. Route is right for questions about subject, status, authority, or relationship, which are not written in the document text itself.

What does it mean when the routing hook prints nothing?

Silence from the intent hook means the route matched nothing, which is a result rather than a failure. It indicates the subject is not one a declared purpose answers, so a text search over the docs tree is then reasonable.

Does headwater-orient replace reading the documents it finds?

No. The skill finishes as soon as the right document is open; it finds but does not read for you. It also never judges whether a document's warrant is correct, which is the job of a coherence sweep with headwater-sweep.