Simple End-To-End Verification Guide¶

This is the shortest useful local proof that the repository is working end to end. It exercises the lookup-first ask path, the repo-level smoke test, and the Makefile/notebook surface verifier without requiring Azure credentials or a full make quality run.

What The Three Main Commands Exercise¶

make ask reaches the repo-rag ask CLI wiring and then the lookup-first retrieval path.
make smoke-test reaches the run_smoke_test(...) helper, which validates baseline answer generation, MCP discovery, and Azure manifest writing together.
make verify-surfaces reaches run_surface_verification(...) over the verify_repository_surfaces(...) contract.

Prerequisites¶

uv sync --extra azure
make hooks-install

The azure extra is still part of the standard sync because the shared CLI, tests, and smoke surfaces import the same package graph even when this specific walkthrough stays local-only.

Three-Command Walkthrough¶

Ask one repository question through the default lookup-first path:

make ask QUESTION="What does this repository research?"

Expected shape:

the output starts with Question: and Answer:
the output includes an Evidence: section because synthesize_answer(...) renders explicit supporting file hits
Run the compact end-to-end smoke test:

make smoke-test

Expected shape:

{
  "answer_contains_repository": true,
  "mcp_candidate_count": 1,
  "manifest_path": "artifacts/azure/repo-rag-smoke.json"
}

Verify the committed repo surfaces:

make verify-surfaces

Expected shape:

{
  "checked_makefile": "Makefile",
  "checked_notebook_count": 5,
  "issue_count": 0,
  "issues": []
}

Optional Baseline I Use Before A Push¶

If you want the slightly broader local baseline that matches the repo's audit loop, run:

uv run python -m compileall src tests
uv run pytest tests/test_utilities.py tests/test_repository_rag_bdd.py
cargo build --manifest-path rust-cli/Cargo.toml

Those commands cover syntax/import health, the utility-facing pytest slice, and the Rust wrapper build without escalating to the heavier full-coverage gate.

Fast Failure Triage¶

If make ask returns weak evidence, inspect the native candidate pass first with make rust-lookup before moving to the DSPy path.
If make smoke-test fails, inspect the three checks inside run_smoke_test(...): answer text, MCP discovery count, and smoke-manifest output.
If make verify-surfaces reports issues, compare the required target list with the current Makefile and notebook headings.