Imported from somacdivad/wayfinder (.agents/skills/build/SKILL.md). Install upstream with npx skills add somacdivad/wayfinder --skill build. Copyright stays with the author.

Build Wayfinder

Use this skill when work needs to draw on or extend the repository's shared context in docs/, whether the request begins with research, knowledge synthesis, planning, or implementation.

Documentation roles

• docs/research/ holds source-specific research records. A record should capture its source, an access log, and the key points relevant to Wayfinder.
• docs/knowledge/ holds the project-specific knowledge graph synthesized from research.
• docs/plans/ holds implementation plans for features, bug fixes, refactors, and related work.

Maintain a traceable chain wherever it applies: sources support research records; research supports knowledge; knowledge informs plans; plans guide implementation. Link to the relevant upstream artifacts when creating or updating a downstream one.

Research workflow

When a user asks to research a topic, begin with a concise research brief. Identify the research question, intended decision or audience, included and excluded scope, relevant jurisdiction, time horizon, and freshness needs. Inspect the available context before asking questions; ask the user only when a material gap would change the research.

Discover sources in this order:

1. Primary and authoritative sources: original research, official documentation, standards bodies, regulators, public datasets, source repositories, and first-party records.
2. Scholarly indexes, library catalogues, and publisher collections to locate peer-reviewed or otherwise rigorously edited material.
3. High-quality independent secondary analysis for context, comparison, and interpretation.

Treat forums, personal posts, unsourced summaries, and search-result snippets as leads rather than evidence, unless the firsthand perspective itself is the research subject. Apply the source evaluation and recording rules in docs/research/README.md before retaining a source.

Create and maintain one source-specific research record for every retained source. Do not create records for ordinary rejected leads. Use the existing template and schema; do not add ad hoc fields. Record source-backed findings as fact, reasoned inferences as interpretation, stated constraints as requirement, adopted conclusions as decision, and possible adverse outcomes as risk. Surface materially unresolved conflicts between credible sources rather than silently reconciling them.

Complete a research pass when the scoped questions are answered, further searching no longer changes material conclusions, and remaining uncertainty is explicit in the records. Do not substitute a fixed source count for these checks.

Wayfinder CLI

Use the local Wayfinder CLI as the deterministic inspection, validation, and generated-view layer for canonical research and knowledge records. Run it from the repository root as python3 .wayfinder/scripts/wayfinder.py. Its JSON output is compact and machine-readable; use --format text only for a human-review view. Read docs/wayfinder-cli.md only when a less common option, error, or graph operation is needed.

Route to the CLI only when the request is covered by one of its bounded, verifiable operations. Do not invoke it merely because it exists: author research and synthesis in the canonical JSON templates, and use repository inspection and stated reasoning for unsupported semantic work.

Keep graph work bounded: provide --limit for broad searches and traversals, and increase traversal depth only when the immediate evidence is insufficient. Treat exit code 0 with an empty result as a valid “no match”; report the explicit fallback when the CLI lacks the requested operation or verification.

Evaluating this skill

When assessing a Build-skill revision, measure its incremental value with a matched no-skill control: hold the model, agent host, repository snapshot, task instruction, allowed tools, and execution budget fixed, and vary only whether this skill is available. Score verified task outcomes—not a plausible response, a skill invocation, or a successful command exit—as the primary measure.

Use a cost-conscious funnel:

1. On every change, run the deterministic repository checks relevant to the fixture: research and knowledge validation, generated-view checks, provenance/reference integrity, and expected-state or diff checks.
2. For a candidate change, screen a balanced, representative suite of about 20 tasks with one randomized-order trial per condition. Include workflow tasks that should use the CLI and negative-routing tasks that should not.
3. Add two to four paired trials only for safety-critical, discordant, apparently regressed, or threshold-near cases. Keep a small held-out suite for confirmation. Human-review a small random sample only to calibrate rubric grading for open-ended research or plan quality.

For each condition, retain the task result and trace; report verified-success rate, safety failures, routing precision and recall, p50/p95 wall time, input/output tokens, command count, and all-in cost. Compare cost per verified success and inspect per-task regressions before accepting an average gain. See docs/knowledge/build-skill-evaluation.md for the evidence-backed protocol and its limits.

Runner selection

For the initial Codex Build-skill pilot, prefer a pinned Promptfoo runner over building a general agent-evaluation framework. It can hold Codex fixtures constant while varying the skill, record route and trace signals, and export cost and latency data. First prove host parity with one read-only and one disposable-write fixture: discovery, permissions, trace capture, cleanup, and the deterministic verifier must match the intended Codex workflow. Do not add it as a gate until that pilot passes.

Keep Wayfinder's fixture definition, matched baseline, CLI/state and allowed-diff verifiers, result schema, and acceptance thresholds canonical in this repository. A skill-used signal, tool call, LLM judge, or runner exit only diagnoses a run; it does not replace verified completion. Escalate to Inspect only for documented multi-host, multi-agent, or advanced-sandbox needs; use BenchFlow for Dockerized cross-agent benchmark suites; defer managed platforms until production traces or multi-maintainer collaboration justify them. See docs/knowledge/skill-plugin-evaluation-framework-selection.md for the comparison, adoption-evidence limits, and decision gates.

Reusable assets and automation

Reserve future reusable record assets in .wayfinder/templates/. Reserve a pure-Python CLI for deterministic operations in .wayfinder/scripts/; do not invent its commands or storage format without a separately established contract.